awssesh

Keep your AWS SSO credentials fresh — automatically. A fast terminal dashboard that auto-refreshes your pinned profiles while it's open.

Why awssesh

• k9s-style list-first dashboard — all your SSO profiles at a glance with live expiry countdowns; navigate with j/k or arrow keys, no menus to dig through.
• In-process auto-refresh for ⟳ pinned profiles — pin a profile with a and expiry-aware refresh keeps its credentials ready before they expire, with no fixed-interval polling waste.
• Notify-on-login, never surprise you — when an interactive SSO login is required awssesh sends a desktop notification so you know to log in.
• One-keystroke everything — copy export AWS_* vars, open the AWS console, copy the profile name, or force a refresh — all from the dashboard without leaving your terminal.
• Single process, clean exit — quitting fully exits. No background processes to manage.

Demo

Install

# Run without installing
npx awssesh
bunx awssesh

# Or install globally
npm install -g awssesh

Quick Start

# 1. Launch the dashboard
awssesh

# 2. Navigate to a profile and press 'a' to pin it for auto-refresh
# 3. awssesh auto-refreshes pinned profiles while the dashboard is open
# 4. Press 'q' to quit when done

While the dashboard is open, ⟳ pinned profiles are refreshed automatically when their credentials are close to expiry. When a browser login is required, you get a desktop notification and can log in directly from the TUI or with awssesh refresh <profile>.

Commands

| Command | Description | |---------|-------------| | awssesh | Launch the interactive TUI | | awssesh status | Print profile statuses and exit | | awssesh refresh [name] | Refresh a profile (or all favorites) now | | awssesh export <name> | Print export AWS_* lines for eval $(...) | | awssesh --version | Print version and exit |

Shell trick — inject credentials into your current shell:

eval $(awssesh export prod)

Keyboard Shortcuts

| Key | Action | |-----|--------| | ↑ / ↓ or j / k | Move cursor | | Enter | Open profile details | | r | Refresh the current profile | | a | Toggle ⟳ auto-refresh (pin/unpin) | | c | Copy export AWS_* to clipboard | | y | Copy profile name to clipboard | | o | Open AWS console in browser | | / | Filter profiles by name | | s | Open settings | | Esc | Back | | q | Quit |

How Auto-Refresh Works

awssesh tracks the role-credential expiry for each ⟳ pinned profile and refreshes only when the credentials are within the lead window of expiring (default: 5 minutes before expiry). No fixed interval; no wasted refreshes.

When an interactive SSO login is needed, a desktop notification is sent (awssesh: <profile> needs login). You authorize by logging in from the TUI or with awssesh refresh <profile>.

Prerequisites

• AWS CLI v2 configured with SSO profiles in ~/.aws/config

Development

Requires Bun >= 1.0.

git clone https://github.com/tux86/awssesh.git
cd awssesh
bun install

bun run start    # Run from source
bun run dev      # Run with --watch (auto-restart on changes)
bun run build    # Build the Node CLI bundle (dist/cli.js)
bun run lint     # Run ESLint
bun test         # Run unit tests

Contributing

• Contributing Guide
• Code of Conduct
• Security Policy

Uses Conventional Commits and release-please.

License

MIT