awsesh

A modern AWS SSO session manager with an interactive TUI, powerful CLI, and a reusable SDK.

Features

• Interactive terminal UI for managing AWS SSO sessions
• Interactive CLI if that's more your jam
• Fast fuzzy search across accounts and roles
• Multiple SSO profile support
• Automatic credential management
• Remappable keybindings
• Browser integration for quick AWS Console access
• Shell integration with environment variable exports
• Reusable SDK for building your own tools
• XDG Base Directory compliant

Installation

Homebrew (macOS/Linux)

brew tap elva-labs/elva
brew install awsesh

Pre-built Binaries

Download the latest release from the Releases page.

# Linux (x64)
curl -L https://github.com/elva-labs/awsesh/releases/latest/download/awsesh-linux-x64 -o awsesh
chmod +x awsesh
mv awsesh ~/.local/bin/

# macOS (Apple Silicon)
curl -L https://github.com/elva-labs/awsesh/releases/latest/download/awsesh-darwin-arm64 -o awsesh
chmod +x awsesh
mv awsesh /usr/local/bin/

Build from Source

Requires Bun 1.3.1+

git clone https://github.com/elva-labs/awsesh.git
cd awsesh
bun install
bun run build

Interactive TUI

Launch the interactive terminal interface:

awsesh

Navigation

Managing SSO Profiles

Account & Role Selection

Active Sessions

View and manage your active credential sessions:

CLI

Use awsesh directly from the command line for scripting and automation.

Quick Usage

# Set credentials
awsesh set

# Set credentials for a specific role
awsesh set <sso-profile> <account-name> <role-name>

# Check current identity
awsesh whoami

# List active sessions
awsesh sessions

# List cached accounts
awsesh accounts

Commands

Options

awsesh [options] [sso] [account] [role]

Options:
  -e, --eval              Output environment variables for shell eval
  -b, --browser           Open AWS Console in browser
  -r, --region <region>   Override region for this session
  -p, --profile <name>    Use custom profile name
  -v, --version           Show version
  -h, --help              Show help

Shell Integration

Add this to your shell config for seamless environment variable integration:

Bash/Zsh:

sesh() { # i personally prefer "sesh" over "awsesh"
    eval "$(command awsesh --eval "$@")"
}

Fish:

function sesh
    eval (command awsesh --eval $argv)
end

When you run awsesh --eval (or sesh in the examples above), awsesh exports AWS credentials plus session metadata:

• AWSESH_ACCOUNT_ID
• AWSESH_ACCOUNT_NAME
• AWSESH_ROLE_NAME
• AWSESH_SESSION_NAME
• AWS_REGION
• AWS_ACCESS_KEY_ID
• AWS_SECRET_ACCESS_KEY
• AWS_SESSION_TOKEN
• AWS_SESSION_EXPIRATION

SDK

The core functionality is available as a standalone SDK for building your own AWS SSO tools.

Installation

npm install @awsesh/core
# or
bun add @awsesh/core

Quick Start

import { createAwsesh } from "@awsesh/core"

const awsesh = createAwsesh({
  configDir: "~/.config/awsesh",
  dataDir: "~/.local/share/awsesh", 
  awsDir: "~/.aws",
})

// List SSO sessions
const sessions = await awsesh.sessions.list()

// Start SSO login
const session = await awsesh.sessions.get("my-org")
const loginInfo = await awsesh.sso.startLogin(session)
console.log(`Open: ${loginInfo.verificationUriComplete}`)

// Poll for token
const token = await awsesh.sso.pollForToken(session, loginInfo)

// List accounts
const accounts = await awsesh.sso.listAccounts(session, token.token)

// Get credentials
const creds = await awsesh.sso.getCredentials(session, token.token, accountId, roleName)

See the full SDK Documentation for detailed API reference.

For a complete working example, see the awsesh-sdk-example repository.

Themes

Awsesh currently supports a bunch of themes, the base one using your terminal colors.

Migrating from Go Version

If upgrading from the original Go version of awsesh the mgiration should run automatically. Otherwise you can run the migration command manually:

awsesh migrate

Options:

• --dry-run - Preview changes without applying
• --force - Force migration even if config exists
• --no-backup - Skip backup (not recommended)

The migration converts your existing profiles, tokens, and preferences to the new JSON format.

Should the migration fail I suggest you to clean up your ~/.aws folder and remove most any awsesh files and the aws files .config and .credentials since they can interfere as well.

Configuration

awsesh follows XDG Base Directory specification:

Settings

Access settings via Ctrl+P > Settings in the TUI, or edit ~/.config/awsesh/config.json:

{
  "theme": "dark",
  "logLevel": "info"
}

Acknowledgments

Huge thanks to the great team over at Anomalyco both for OpenTui and the structure of OpenCode from a few months ago. I shamelessly based the refactor on the structure of OpenCode at the time and it's been great for me.

License

MIT - see LICENSE for details.