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

---

Made with ❤ by tux86