SSOmatic

Interactive AWS SSO credential manager with CLI and web UI.

---

Demo

CLI

Web UI

Features

• Auto-discovery — Scans ~/.aws/config for SSO profiles (legacy and sso_session)
• Status dashboard — View credential validity with expiry countdown
• Multi-select refresh — Refresh multiple profiles at once with SSO device auth
• Auto-refresh daemon — Background process to keep credentials fresh
• Built-in web UI — Toggle a web server from the CLI with w for a browser-based dashboard
• Desktop notifications — Alerts when credentials expire (macOS/Linux)
• Persistent settings — Notifications, favorites, web server, port — all saved across sessions

Prerequisites

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

Install

Homebrew (macOS / Linux)

brew install tux86/tap/ssomatic

Download binary

Grab the latest binary for your platform from Releases:

Platform	Binary
macOS (Apple Silicon)	ssomatic-darwin-arm64.bin
Linux (x64)	ssomatic-linux-x64.bin
Linux (ARM64)	ssomatic-linux-arm64.bin

chmod +x ssomatic-*.bin
mv ssomatic-*.bin /usr/local/bin/ssomatic

From source

Requires Bun >= 1.0.

git clone https://github.com/tux86/ssomatic.git
cd ssomatic
bun install
bun run build
./dist/ssomatic

Usage

ssomatic                # Launch the CLI

Press w to toggle the built-in web UI server. The URL is shown at the bottom of the terminal. Web server state and port are saved in settings.

Development

bun run start         # Run from source
bun run dev           # Run with --watch (auto-restart on changes)
bun run build         # Build web assets + compiled binary
bun run lint          # Run ESLint

Project Structure

ssomatic/
├── src/
│   ├── aws/           # Shared AWS credential logic (sso.ts, aws.ts, utils.ts)
│   ├── cli/           # Terminal UI (React/Ink) — entry point
│   │   ├── index.tsx   # Main app + web server toggle
│   │   ├── components/ # Ink UI components
│   │   └── hooks/      # useIdentity, useCopy
│   └── web/
│       ├── server.ts   # Bun HTTP server + RPC bridge
│       └── client/     # Web UI SPA (React/Vite/Tailwind)
├── dist/              # Build output (single binary, web assets embedded)
└── package.json

Keyboard Shortcuts

Key	Action
↑/↓ or j/k	Navigate
Enter	Select
Space	Toggle selection
a	Select all / none
w	Toggle web server
c	Copy URL
Escape	Back
q	Quit

Contributing

• Contributing Guide
• Code of Conduct
• Security Policy

Uses Conventional Commits and semantic-release.

License

MIT

---

Made with ❤ by tux86