{"id":35871230,"url":"https://github.com/elva-labs/awsesh","last_synced_at":"2026-05-04T12:01:38.627Z","repository":{"id":284505896,"uuid":"951414705","full_name":"elva-labs/awsesh","owner":"elva-labs","description":"An AWS session and credential manager and SDK (beta) ✨","archived":false,"fork":false,"pushed_at":"2026-03-18T19:44:29.000Z","size":23550,"stargazers_count":124,"open_issues_count":6,"forks_count":4,"subscribers_count":10,"default_branch":"main","last_synced_at":"2026-03-19T08:49:51.166Z","etag":null,"topics":["aws","aws-sso","bubbletea","charm","cli","go","golang","opentui","sso","terminal","tui","typescript"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/elva-labs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-03-19T16:33:27.000Z","updated_at":"2026-03-11T00:25:17.000Z","dependencies_parsed_at":"2025-04-15T10:22:28.399Z","dependency_job_id":"fd1273c5-4cb3-48a1-a614-d73e09d87ec7","html_url":"https://github.com/elva-labs/awsesh","commit_stats":null,"previous_names":["elva-labs/awsesh"],"tags_count":41,"template":false,"template_full_name":null,"purl":"pkg:github/elva-labs/awsesh","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elva-labs%2Fawsesh","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elva-labs%2Fawsesh/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elva-labs%2Fawsesh/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elva-labs%2Fawsesh/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/elva-labs","download_url":"https://codeload.github.com/elva-labs/awsesh/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elva-labs%2Fawsesh/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32606413,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-04T10:08:07.713Z","status":"ssl_error","status_checked_at":"2026-05-04T10:08:02.005Z","response_time":58,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aws","aws-sso","bubbletea","charm","cli","go","golang","opentui","sso","terminal","tui","typescript"],"created_at":"2026-01-08T15:18:48.712Z","updated_at":"2026-05-04T12:01:38.596Z","avatar_url":"https://github.com/elva-labs.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# (AW)Sesh 🔐\n\n## Beta testing of new version available!\n\nCurrently I'm testinga new version of awsesh on the beta branch.\nIt's a major rewrite to TypeScript and an API-based architecture that makes it ripe for plugin-ability and scripting as well.\nPlease check it out if you are new here!\n\n```sh\nbrew tap elva-labs/elva\nbrew install awsesh-beta\n```\n[Link to branch here](https://github.com/elva-labs/awsesh/tree/beta)\n\n## What is it?\n\nSesh is a simple to use AWS session manager with charm! ✨💕\n\nSesh is made to easily manage your AWS SSO sessions and accounts.\nFilter your accounts by name, and quickly switch between them.\n\n![sesh demo](tapes/demo2.gif)\n_Basic demo_\n\n![sesh editing and removing](tapes/editing-removing.gif)\n_Editing, removing, managing SSO, setting region per account, and opening in browser._\n\n## ✨ Features\n\n- 🚀 Quick AWS SSO session management\n- 🔄 Fast account switching\n- 🔍 Fuzzy search filtering for accounts\n- 🌐 Open the AWS console in your browser\n- 💅 Charming interactive terminal user interface\n- 🪶 Lightweight and easy to install\n- 🏷️ Profile support\n- ⭐ Compatible with shell prompt tools like Starship\n- 📁 XDG Base Directory specification compliance\n\n## 📋 Prerequisites\n\n- Go 1.x (Only required if building from source)\n\n## 📦 Installation\n\nThere are several ways to install Sesh:\n\n### Homebrew (Recommended - Linux/macOS)\n\nIf you have [Homebrew](https://brew.sh/) installed, you can install `sesh` with:\n\n```sh\nbrew tap elva-labs/elva\nbrew install awsesh\n```\n\n### Installation Script\n\nDownload and run the installation script:\n\n```sh\ncurl -sSL https://raw.githubusercontent.com/elva-labs/awsesh/main/install.sh | bash\n```\n\n_This script will attempt to install `sesh` to `/usr/local/bin` or `~/.local/bin` and will prompt for `sudo` if necessary._\n\n### Pre-built Binaries\n\nDownload the latest release executables directly from the [Releases page](https://github.com/elva-labs/awsesh/releases/latest).\n\n**Linux/macOS:**\n\n1. Download the appropriate binary (`sesh-linux-amd64`, `sesh-linux-arm64`, `sesh-darwin-amd64`, `sesh-darwin-arm64`). Example for Linux x86_64:\n\n   ```bash\n   curl -L https://github.com/elva-labs/awsesh/releases/latest/download/sesh-linux-amd64 -o sesh\n   ```\n\n2. Make it executable:\n\n   ```bash\n   chmod +x sesh\n   ```\n\n3. Move it to a directory in your PATH:\n\n   ```bash\n   # For system-wide installation (may require sudo depending on permissions):\n   mv sesh /usr/local/bin/\n\n   # Or for user-local installation:\n   mkdir -p ~/.local/bin\n   mv sesh ~/.local/bin/\n   ```\n\n4. If using `~/.local/bin`, ensure it's in your PATH:\n\n   ```bash\n   # Add this to your ~/.bashrc, ~/.zshrc, or equivalent if needed\n   export PATH=\"$HOME/.local/bin:$PATH\"\n   ```\n\n**Windows:**\n\n1. Download the Windows executable (`sesh-windows-amd64.exe`).\n2. Create a folder (e.g., `%LOCALAPPDATA%\\Programs\\sesh\\`).\n3. Move the downloaded file there and rename it to `sesh.exe`.\n4. Add the folder to your PATH via System Properties or PowerShell:\n\n   ```powershell\n   # Ensure the target directory exists\n   New-Item -ItemType Directory -Force \"$env:LOCALAPPDATA\\Programs\\sesh\"\n   # Add to user PATH (requires restart of terminal/session)\n   $CurrentUserPath = [Environment]::GetEnvironmentVariable('Path', 'User')\n   $NewPath = $CurrentUserPath + \";$env:LOCALAPPDATA\\Programs\\sesh\"\n   [Environment]::SetEnvironmentVariable('Path', $NewPath, 'User')\n   ```\n\n### Build from Source\n\n1. Clone the repository:\n\n   ```sh\n   git clone https://github.com/elva-labs/awsesh.git\n   cd awsesh\n   ```\n\n2. Build the application:\n\n   **Linux/macOS:**\n\n   ```sh\n   go build -ldflags=\"-X main.Version=$(git describe --tags --always)\" -o sesh\n   ```\n\n   **Windows:**\n\n   ```powershell\n   # Set environment variables for cross-compilation if needed\n   # $env:GOOS = \"windows\"\n   # $env:GOARCH = \"amd64\"\n   go build -o build/sesh.exe\n   ```\n\n3. Install the binary (move it to your PATH):\n\n   **Linux/macOS:**\n\n   ```sh\n   # For system-wide installation (may require sudo depending on permissions):\n   cp build/sesh /usr/local/bin/\n\n   # For user-local installation:\n   mkdir -p ~/.local/bin\n   cp build/sesh ~/.local/bin/\n\n   # Ensure it's executable\n   chmod +x /usr/local/bin/sesh  # Or ~/.local/bin/sesh\n   ```\n\n   **Windows:**\n\n   ```powershell\n   # Ensure the target directory exists\n   New-Item -ItemType Directory -Force \"$env:LOCALAPPDATA\\Programs\\sesh\"\n   # Copy the binary\n   Copy-Item \"build\\sesh.exe\" \"$env:LOCALAPPDATA\\Programs\\sesh\\sesh.exe\"\n   # Add to user PATH (see Pre-built Binaries section for command)\n   ```\n\n## 🚀 Usage\n\n### Interactive TUI\n\nSimply run `sesh` to launch the interactive terminal interface:\n\n```sh\nsesh\n```\n\n### Command Line Interface (CLI)\n\nYou can also use `sesh` directly from the command line:\n\n```sh\nsesh [-v|--version] [-b|--browser] [-w|--whoami] [-r|--region REGION] [-e|--eval] [-p|--profile PROFILE] [SSONAME ACCOUNTNAME [ROLENAME]]\n```\n\n**Examples:**\n\n- Open the AWS console in a browser for a specific role:\n\n  ```sh\n  sesh MyOrg MyAccount AdminRole -b\n  ```\n\n- Set the region for the session:\n\n  ```sh\n  sesh MyOrg MyAccount AdminRole -r eu-west-1\n  ```\n\n- If you've previously selected a role for an account in the TUI, `sesh` remembers it for CLI usage:\n\n  ```sh\n  # Assumes AdminRole was previously selected for MyOrg/MyAccount in the TUI\n  sesh MyOrg MyAccount -b\n  ```\n\n- Use a custom profile name for your credentials:\n\n  ```sh\n  sesh MyOrg MyAccount AdminRole --profile production\n  ```\n\n- Use custom profile with last used role (no need to specify role):\n\n  ```sh\n  sesh MyOrg MyAccount --profile production\n  ```\n\n- Combine custom profile with shell integration:\n\n  ```sh\n  sesh MyOrg MyAccount AdminRole --profile dev\n  ```\n\n### Shell Integration\n\nUse the `--eval` flag to set AWS environment variables in your shell for seamless integration with tools like [Starship](https://starship.rs/).\n\n#### Setup\n\nAdd this function to your shell configuration (`~/.bashrc`, `~/.zshrc`, etc.):\n\n**Bash/Zsh:**\n\n```bash\nsesh() {\n    eval \"$(command sesh --eval \"$@\")\"\n}\n```\n\n**Fish:**\n\n```fish\nfunction sesh\n    eval (command sesh --eval $argv)\nend\n```\n\n#### Usage\n\n```sh\n# CLI mode\nsesh MyOrg MyAccount AdminRole\n\n# TUI mode\nsesh\n```\n\nThis sets all AWS environment variables for compatibility with AWS tools and shell prompts:\n\n```bash\nexport AWS_PROFILE='myorg-adminrole'\nexport AWS_REGION='us-east-1'\nexport AWS_ACCESS_KEY_ID='AKIA...'\nexport AWS_SECRET_ACCESS_KEY='...'\nexport AWS_SESSION_TOKEN='...'\nexport AWS_SESSION_EXPIRATION='2024-08-19T10:30:00Z'\n```\n\n### Custom Profile Names\n\nBy default, `sesh` writes credentials to the `default` profile in your AWS credentials file. You can specify a custom profile name using the `--profile` flag.\n\n**CLI Usage:**\n\n```bash\n# Use a custom profile name\nsesh MyOrg MyAccount AdminRole --profile production\n```\n\n**TUI Usage:**\nIn the interactive mode, when selecting a role, press `p` to enter a custom profile name before setting credentials. The input will be pre-filled with the previously used profile name for that specific account and role combination.\n\n#### Profile Name Memory\n\n`sesh` remembers the custom profile names you use for specific account+role combinations:\n\n- **First time**: `sesh MyOrg MyAccount AdminRole --profile production`\n- **Next time**: `sesh MyOrg MyAccount --profile production` (automatically uses AdminRole)\n- **TUI**: Press `p` on \"MyAccount/AdminRole\" → input pre-filled with \"production\"\n\nThis makes it easy to consistently use the same profile names for your different environments without having to remember or retype them.\n\n#### Profile Naming Convention\n\n- **Default behavior**: Uses the `default` profile\n- **With `--profile` flag**: Uses your specified profile name\n- **Shell integration**: Automatically sets `AWS_PROFILE` environment variable\n\n### Important Notes\n\n#### Credentials File Modification\n\n\u003e **❗ Important Notice ❗**\n\u003e\n\u003e This application **will edit** your AWS credentials file to set the session keys. By default, this is `~/.aws/credentials`, but `sesh` respects the `AWS_SHARED_CREDENTIALS_FILE` environment variable if set. If you have a complex or custom setup in this file, please **back it up** before using `sesh`.\n\n#### XDG Base Directory Compliance\n\n`sesh` supports XDG Base Directory specification and respects the following environment variables:\n\n- `AWS_CONFIG_FILE` - Path to AWS config file (default: `~/.aws/config`)\n- `AWS_SHARED_CREDENTIALS_FILE` - Path to AWS credentials file (default: `~/.aws/credentials`)\n\n**Example XDG setup:**\n\n```bash\nexport AWS_CONFIG_FILE=\"$XDG_CONFIG_HOME/aws/config\"\nexport AWS_SHARED_CREDENTIALS_FILE=\"$XDG_DATA_HOME/aws/credentials\"\n```\n\nWhen these environment variables are set, `sesh` will:\n\n- Read existing SSO profiles from the custom config location\n- Write credentials to the custom credentials location\n- Store its own configuration files (`awsesh`, `awsesh-tokens`, etc.) in the same directory as your AWS config file\n\n**Example with XDG compliance:**\n\n```bash\n# Set XDG-compliant paths\nexport AWS_CONFIG_FILE=\"$XDG_CONFIG_HOME/aws/config\"\nexport AWS_SHARED_CREDENTIALS_FILE=\"$XDG_DATA_HOME/aws/credentials\"\n\n# Use sesh with shell integration\nsesh MyOrg MyAccount AdminRole\n\n# Credentials file and environment variables are set\necho $AWS_PROFILE  # Output: myorg-adminrole\naws sts get-caller-identity  # Works with custom location\n```\n\n\u003e **💡 Note for XDG users:** If you have `AWS_CONFIG_FILE` set but your SSO profiles don't appear, make sure your existing SSO profiles are in the file specified by that environment variable, not in `~/.aws/config`.\n\n#### Large Number of SSO Accounts\n\nThere is a known issue where fetching roles for AWS SSO setups with a very large number of accounts (\u003e100) can trigger AWS API rate limiting (429 errors). To mitigate this, `sesh` only automatically fetches roles on startup if there are fewer than 100 accounts. For larger setups, roles are lazy-loaded when you select an account in the TUI.\n\n## 🧹 Uninstall\n\n### Using the Uninstall Script (Linux/macOS)\n\nIf you installed `sesh` using the installation script, you can run the corresponding uninstall script:\n\n```sh\ncurl -sSL https://raw.githubusercontent.com/elva-labs/awsesh/main/uninstall.sh | bash\n```\n\n- You might be prompted for your password if `sesh` was installed in `/usr/local/bin`.\n- The script will attempt to remove `sesh` from `/usr/local/bin` and `~/.local/bin`.\n- If `sesh` was installed to `~/.local/bin` and removed, the script will remind you to remove the directory from your `PATH` in your shell configuration file (`.bashrc`, `.zshrc`, etc.) if you added it manually.\n\n### Manual Uninstall\n\n**Linux/macOS:**\n\n1. **Locate the binary:** Check common locations: `/usr/local/bin/sesh`, `~/.local/bin/sesh`.\n2. **Remove the binary:**\n   - `rm /usr/local/bin/sesh` (may require `sudo` depending on how it was installed)\n   - `rm ~/.local/bin/sesh`\n3. **Remove from PATH (if applicable):** If you manually added `~/.local/bin` to your `PATH`, remove that line from your shell configuration file (e.g., `~/.bashrc`, `~/.zshrc`).\n\n**Windows:**\n\n1. **Remove the executable:** Delete `sesh.exe` (typically in `%LOCALAPPDATA%\\Programs\\sesh\\`).\n2. **Remove from PATH:** Edit your User Environment Variables (search for \"Environment Variables\"), select \"Path\", find the entry for the `sesh` directory, and delete it. Click OK. You may need to restart your terminal or session.\n\n## 🛠️ Built With\n\n- [Go](https://golang.org/) 🐹\n- [Charm](https://charm.sh/) Tools ✨\n  - [Bubble Tea](https://github.com/charmbracelet/bubbletea)\n  - [Bubbles](https://github.com/charmbracelet/bubbles)\n  - [Lip Gloss](https://github.com/charmbracelet/lipgloss)\n  - [VHS](https://github.com/charmbracelet/vhs) (for demo recording)\n- [AWS SDK for Go V2](https://github.com/aws/aws-sdk-go-v2) ☁️\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felva-labs%2Fawsesh","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Felva-labs%2Fawsesh","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felva-labs%2Fawsesh/lists"}