switch-profile 1.1.0 → 2.0.0

package/README.md

@@ -1,163 +1,246 @@
 # switch-profile
 
-An interactive CLI tool for switching between AWS profiles directly from your terminal. No more manually editing `~/.aws/credentials` or juggling environment variables.
+Switch between AWS profiles from your terminal. Type a few letters, press enter, and every AWS tool uses that account. SSO logins work on remote machines too (device code, clipboard over SSH, QR code), and each terminal can stay on its own account.
+
+```
+┌   switch-profile  2.0.0
+│
+│  ● acme-prod · Admin · 111111111111 · ap-southeast-2 · PROD · SSO ✓ auto-refresh · logged in 3h ago
+│
+◆  Switch to · type a name, account, role or client
+│  Search: dev▌
+│  ● acme-dev        Admin     222222222222  ap-southeast-2   (used 2d ago)
+│  ○ globex-dev      ReadOnly  333333333333  us-east-1
+│  ○ initech-dev     Admin     444444444444  eu-west-1
+└
+```
+
+- **Fast picker.** Fuzzy search across profile name, account id, account name, role, SSO session (client) and region. The profiles you use most come first.
+- **One identity check per switch.** `switch-profile` calls `aws sts get-caller-identity` once, logs in if needed, then makes the profile the default.
+- **Auto-refresh.** It writes the profile's *settings* into `[default]`, never temporary credentials, so the AWS CLI, SDKs and Terraform refresh credentials on their own.
+- **Per-terminal.** With the `sp` shortcut, the current terminal also gets `AWS_PROFILE`, so different terminals can use different accounts. `sp` also adds tab-completion.
+- **Remote-friendly.** Over SSH, logins use a device code: the code is copied to your laptop's clipboard and the URL can be shown as a QR code.
+- **Import a whole portal.** `sp add` creates one profile per account and role of an IAM Identity Center portal.
+- **Script and agent friendly.** Never prompts when there is no terminal, `--json` output, stable exit codes.
+
+## Table of Contents
+
+<!-- BEGIN toc -->
+- [Quick start](#quick-start)
+- [Commands](#commands)
+- [Working on remote machines (SSH)](#working-on-remote-machines-ssh)
+- [Importing a client's accounts](#importing-a-clients-accounts)
+- [Scripts and AI agents](#scripts-and-ai-agents)
+- [Settings](#settings)
+  - [The `sp` shortcut](#the-sp-shortcut)
+- [Upgrading from 1.x](#upgrading-from-1x)
+- [Requirements](#requirements)
+- [Troubleshooting](#troubleshooting)
+  - [`invalid_grant` during an SSO login](#invalid_grant-during-an-sso-login)
+  - [`Error loading SSO Token` or "session has expired"](#error-loading-sso-token-or-session-has-expired)
+  - [SSO login hangs on a remote machine](#sso-login-hangs-on-a-remote-machine)
+  - [The code is not in my clipboard over SSH](#the-code-is-not-in-my-clipboard-over-ssh)
+  - [`sp: command not found`](#sp-command-not-found)
+  - [Tab-completion does not work in zsh](#tab-completion-does-not-work-in-zsh)
+  - [Commands still use the wrong account](#commands-still-use-the-wrong-account)
+  - [AWS CLI not found](#aws-cli-not-found)
+- [Documentation](#documentation)
+- [License](#license)
+<!-- END toc -->
+
+## Quick start
 
 ```shell
 npx switch-profile
 ```
 
-## Why?
+On the first switch, `switch-profile` offers to set up the `sp` shortcut (a small function in your shell startup file). Say yes, open a new terminal, and from then on:
 
-AWS SSO credentials expire every hour. Without `switch-profile`, refreshing them means either:
+```shell
+sp                 # pick a profile
+sp acme-prod       # switch straight to a profile
+sp acme prod       # fuzzy match: switches if exactly one profile matches
+```
+
+For speed, install it globally. `npx` checks the npm registry on every run, which adds a noticeable delay; `sp` uses the global command when it exists and falls back to `npx` otherwise.
+
+```shell
+npm install -g switch-profile
+```
 
-1. **Manual copy-paste** - Browse to the SSO portal, log in, reveal credentials, paste them into your terminal or `~/.aws/credentials` file. Repeat every hour.
-2. **Per-command `--profile` flag** - Use `aws sso login --profile <name>`, but then every command (and every tool like Terraform) needs `--profile`. Not always possible or practical.
+No profiles yet? `switch-profile` starts the **Add profiles** flow. To import every account of your company's or client's SSO portal, see [Importing a client's accounts](#importing-a-clients-accounts).
 
-`switch-profile` makes setting any AWS profile as `default` trivial - one command, pick from a list, done. It handles SSO session refresh automatically, including opening the browser for re-authentication when sessions expire.
+## Commands
 
-## Prerequisites
+| Command | What it does |
+|---------|--------------|
+| `switch-profile [profile...]` | Opens the picker. With words: an exact name or a unique fuzzy match switches directly; otherwise the picker opens pre-filtered (or exits 3 when non-interactive). |
+| `use <profile>` | Switches to a profile by its exact name (no fuzzy matching). |
+| `status [--json]` | Shows the default profile, its login state, and what this terminal uses. |
+| `login [profile] [--device\|--browser]` | Starts a fresh login now, even if the session is still valid. Defaults to this terminal's `AWS_PROFILE`, then the default profile. |
+| `logout [--yes]` | Ends every SSO session on this machine (`aws sso logout`, plus `aws logout --all` on AWS CLI 2.32+). |
+| `add` | Adds profiles: import accounts from an SSO portal (recommended), a single SSO profile, a console sign-in profile, or access keys. |
+| `add --from-sso [session]` | Imports or re-syncs every account and role of an `[sso-session]`. Options: `--region`, `--prefix`, `--prune`, `--yes`. |
+| `remove [profiles...] [--yes]` | Removes profiles (alias `rm`). The current default cannot be removed. |
+| `settings` | Per-terminal switching, SSO login mode, legacy SSO upgrade. |
 
-- **[AWS CLI v2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)** - Version 2 or later is required.
-- **Node.js** - Any recent version that supports `npx`.
+Global options: `--json`, `--no-input` (never prompt), `--debug` (show stack traces), `-v, --version`. In examples, `sp` and `switch-profile` are interchangeable; only `sp` changes the current terminal.
 
-> **Important:** Remove these environment variables from your shell if they are set, as they override the default profile and will conflict with `switch-profile`:
-> - `AWS_ACCESS_KEY_ID`
-> - `AWS_SECRET_ACCESS_KEY`
-> - `AWS_SESSION_TOKEN`
+See [CLI Interface](docs/cli-interface.md) for every screen.
 
-## Installation
+## Working on remote machines (SSH)
 
-No installation needed. Run directly with npx:
+Since AWS CLI 2.22, `aws sso login` opens a browser on the machine running the CLI. Over SSH there is none, so the login hangs. `switch-profile` detects remote sessions (`SSH_CONNECTION`, `SSH_CLIENT` or `SSH_TTY` set, or Linux without `DISPLAY`/`WAYLAND_DISPLAY`) and uses a device code instead:
 
-```shell
-npx switch-profile
 ```
+◇  Approve the login for acme
 
-Or install globally:
+   Open  https://device.sso.us-east-1.amazonaws.com/?user_code=WXYZ-ABCD
+   Code  WXYZ-ABCD  📋 sent to your clipboard
 
-```shell
-npm install -g switch-profile
-switch-profile
+   🔒 Only approve if the page shows exactly this code.
+   q QR code · c copy again · ctrl+c cancel
+◒  Waiting for approval 0:12
 ```
 
-## Quick Start
+- **Clipboard over SSH.** The code is sent to your local clipboard with the OSC 52 terminal escape sequence. iTerm2, Ghostty, kitty, WezTerm and Windows Terminal support it; tmux needs `set -g set-clipboard on` (or `allow-passthrough on`). If your terminal ignores it, copy the code by hand.
+- **QR code.** Press `q` to show the URL as a QR code and approve from your phone.
+- **Log in any time.** `sp login` starts a fresh session now, for example before a long task. `--device` and `--browser` override the automatic choice; Settings can make either permanent.
+- **Log out.** `sp logout` ends every SSO session on the machine, so a shared or rented server keeps no AWS access.
+
+How often you log in is set by IAM Identity Center, not by `switch-profile`:
 
-### Switch between existing profiles
+- The **user interactive session** duration decides when you must log in again. The default is 8 hours, up to 90 days. Your administrator sets it once for the whole Identity Center instance (Settings > Authentication).
+- The **permission set** session duration (1 to 12 hours) matters less: role credentials refresh automatically while the SSO session is valid, as long as the profile uses an `[sso-session]` (the format `switch-profile` writes).
+
+## Importing a client's accounts
 
 ```shell
-npx switch-profile
+sp add          # then choose "Accounts from an SSO portal"
 ```
 
-This will:
-1. Show your current default profile with its expiry status.
-2. List all available profiles.
-3. Let you pick one to set as the new `default`.
-4. Display an `export AWS_PROFILE=<name>` command you can run to lock that profile to your current terminal session.
+1. Pick an existing `[sso-session]` or create one: start URL (e.g. `https://acme.awsapps.com/start`), SSO region (where Identity Center lives, not where you deploy), and a short name, usually the client.
+2. Log in if needed.
+3. `switch-profile` lists every account and role you can access, then asks for a default region and a name prefix. Profiles are named `<prefix>-<account-name>-<role>`, for example `acme-prod-workloads-admin`.
+4. A preview shows the new profiles, the ones already set up, and the ones that no longer exist. Confirm to write them.
 
-For SSO profiles, if the session has expired, it automatically opens your browser for re-authentication.
+Run it again later to pick up new accounts. Account/role pairs that already have a profile are never duplicated, whatever its name. Generated profiles that no longer exist can be pruned (after a backup); profiles you wrote by hand are never pruned.
 
-### Create a new profile
+Non-interactive (after `aws sso login --sso-session acme` or `sp login`):
 
 ```shell
-npx switch-profile
-# Select "More options" > "Create profile"
+switch-profile add --from-sso acme --region eu-west-1 --prefix acme --yes --json
 ```
 
-You can create:
-- **Standard profiles** - Access key + secret key pair.
-- **SSO profiles** - Launches the interactive `aws configure sso` flow.
+## Scripts and AI agents
+
+`switch-profile` never prompts when stdin or stdout is not a terminal, when `CI` is set, or with `--no-input`. It fails with a hint and an exit code instead.
+
+| Exit code | Meaning |
+|-----------|---------|
+| 0 | OK |
+| 1 | Error |
+| 2 | Login required (run `switch-profile login <profile>` in a terminal) |
+| 3 | Bad input: unknown or ambiguous profile, missing argument or `--yes` |
+| 130 | Cancelled |
 
-### Delete profiles
+- `--json` prints machine-readable results on stdout. Expected errors are printed as JSON on stderr: `{"error": "...", "hint": "...", "code": 3}`.
+- `switch-profile status --json` lists every profile with its kind, account, role, region and whether it is production.
+- Non-interactive logins still work: `switch-profile login acme-dev --device` prints the AWS CLI's URL and code on stderr and waits for approval.
+- A shell tool's environment does not survive between commands, so `sp` and `export AWS_PROFILE` do not help an agent. Prefix each AWS command instead:
 
 ```shell
-npx switch-profile
-# Select "More options" > "Delete profiles"
+AWS_PROFILE=acme-dev aws s3 ls
+AWS_PROFILE=acme-dev terraform plan
 ```
 
-Select one or more profiles to remove. The current default profile cannot be deleted (switch to another one first).
-
-### Refresh an expired profile
+## Settings
 
 ```shell
-npx switch-profile
-# Select "More options" > "Refresh default profile"
+sp settings
 ```
 
-This option only appears when the current default profile has expired. It forces a new SSO login and refreshes the credentials.
+- **Per-terminal switching**: turns the `sp` shortcut (and tab-completion) on or off.
+- **SSO login**: `auto` (device code over SSH, browser otherwise), always device code, or always browser.
+- **Legacy SSO profiles**: upgrades SSO profiles that have no `[sso-session]` (no auto-refresh).
+
+The tool's own state lives in `~/.switch-profile/settings.json`. See [Configuration Files](docs/configuration-files.md).
 
-## How It Works
+### The `sp` shortcut
 
-`switch-profile` manages two AWS configuration files:
+`sp` is a shell function added to your startup file inside a `# >>> switch-profile ... >>>` block. It runs `switch-profile`, then sets `AWS_PROFILE` in the current terminal and clears `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_SESSION_TOKEN` and `AWS_DEFAULT_PROFILE`, which would otherwise override the profile. It also completes profile names and subcommands with Tab. Do not edit the block: `switch-profile` rewrites it when a new version changes it.
 
-| File | Purpose |
-|------|---------|
-| `~/.aws/config` | Stores profile settings (region, output format, SSO metadata) |
-| `~/.aws/credentials` | Stores access keys, secret keys, and session tokens |
+| Shell | Startup file |
+|-------|--------------|
+| zsh | `${ZDOTDIR:-~}/.zshrc` |
+| bash | `~/.bashrc` (Linux), `~/.bash_profile` (macOS) |
+| fish | `~/.config/fish/config.fish` |
+| PowerShell | `$PROFILE.CurrentUserAllHosts` (for `pwsh` and/or Windows PowerShell) |
 
-When you select a profile, `switch-profile`:
-1. Retrieves the credentials for that profile (from cache or via SSO login).
-2. Writes them into the `[default]` section of both files.
-3. Records the profile name and expiry date for status display.
-4. Shows an `export AWS_PROFILE=<name>` command to optionally lock the profile to your terminal session.
+## Upgrading from 1.x
 
-### Per-terminal profile isolation
+Version 1.x copied temporary credentials into `[default]` of `~/.aws/credentials`, which expired after about an hour. Version 2 upgrades your setup automatically on its first run:
 
-By default, switching profiles updates the global `[default]` section, which affects all terminals. If you need different AWS profiles in different terminals simultaneously, copy and run the command shown after each switch (`export AWS_PROFILE=<name>` on Linux/macOS, or the PowerShell/CMD equivalent on Windows). This sets an environment variable scoped to that terminal only, so other terminals remain unaffected.
+- `~/.aws/config` and `~/.aws/credentials` are backed up next to themselves (e.g. `~/.aws/config.bak-2026-10-01T10-12-00Z`).
+- `[default]` is rewritten with the settings of the profile you last selected, and the 1.x `profile` and `expiry_date` keys are removed.
+- If some SSO profiles use the legacy format (no `sso_session`), you are asked once whether to upgrade them. Profiles of the same portal share one session, so one login covers them all.
 
-For SSO profiles specifically, it leverages two additional AWS CLI cache directories:
-- `~/.aws/sso/cache/` - SSO session tokens (long-lived, ~24 hours)
-- `~/.aws/cli/cache/` - Temporary AWS credentials (short-lived, ~1 hour)
+The old `switch-profile switch` command still works. If you run 1.x again later (e.g. `npx switch-profile@1`), the next 2.x run repairs `[default]` (with backups).
 
-## Detailed Documentation
+## Requirements
 
-For deeper technical details, see the docs below:
+- **Node.js 20.12 or later.** Older versions get a clear message.
+- **[AWS CLI v2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html).** 2.22 or later is recommended (choice between device code and browser login); console sign-in (`aws login`) needs 2.32+.
+- **macOS and Linux** are first-class (zsh, bash, fish). **Windows PowerShell** is supported. **CMD** is limited: no `sp`, so run the `set AWS_PROFILE=<name>` command shown after each switch.
 
-| Document | Description |
-|----------|-------------|
-| [Architecture](docs/architecture.md) | Project structure, source files, and how the components fit together |
-| [AWS Profile Management](docs/aws-profile-management.md) | How AWS profiles, SSO sessions, and credentials are managed internally |
-| [CLI Interface](docs/cli-interface.md) | Detailed walkthrough of every menu, prompt, and user flow |
-| [Configuration Files](docs/configuration-files.md) | Exact formats of all AWS and internal configuration files |
-| [Development Guide](docs/development-guide.md) | How to set up, develop, test, lint, and release |
-| [Gotchas](docs/gotchas.md) | Critical pitfalls — global profile switching, per-terminal isolation limits, and LLM agent constraints |
+The published package has no runtime dependencies: everything is bundled into one file.
 
 ## Troubleshooting
 
-### `invalid_grant: Invalid grant provided`
+### `invalid_grant` during an SSO login
+
+The SSO region is wrong. It must be the region of your IAM Identity Center instance, not the region you deploy to. Fix `sso_region` in the `[sso-session]` section of `~/.aws/config` (or remove the portal and add it again).
+
+### `Error loading SSO Token` or "session has expired"
 
-This error occurs during SSO profile creation when the **wrong SSO region** is specified. AWS SSO is region-specific - you must use the region where your SSO instance is configured, not the region you want to deploy resources to.
+The SSO login is missing or expired. Run `sp login` (or just switch to the profile again: `switch-profile` logs in when needed). There is no need to recreate the profile.
 
-**Fix:** Delete the profile and recreate it with the correct SSO region.
+### SSO login hangs on a remote machine
 
-### `Error: Fail to get credentials for profile ... Error loading SSO Token...`
+The AWS CLI is waiting for a browser on the remote machine. Run `sp login --device`, or set **Settings > SSO login** to always use a device code.
 
-This typically happens after the `~/.aws/sso/cache` folder has been deleted or corrupted. This folder tracks SSO sessions and cannot be reconstructed automatically.
+### The code is not in my clipboard over SSH
 
-**Fix:** Delete the affected SSO profiles and recreate them:
+Your terminal does not accept OSC 52, or tmux blocks it. In tmux, add `set -g set-clipboard on` to `~/.tmux.conf`. Otherwise copy the code from the screen (press `c` to try again).
 
-1. Run `npx switch-profile`
-2. Select **More options** > **Delete profiles**
-3. Remove the broken SSO profiles
-4. Recreate them via **More options** > **Create profile**
+### `sp: command not found`
+
+The terminal was opened before `sp` was set up. Open a new terminal or run `source ~/.zshrc` (or your shell's equivalent). `sp settings` shows whether it is on.
+
+### Tab-completion does not work in zsh
+
+The completion registers only if `compinit` ran before the `switch-profile` block. Move the block below `compinit` (or below the line that loads oh-my-zsh) in `~/.zshrc`.
+
+### Commands still use the wrong account
+
+`AWS_ACCESS_KEY_ID`/`AWS_SECRET_ACCESS_KEY` in the environment override every profile, and `AWS_REGION` overrides the profile's region. The picker warns about them; switching with `sp` clears the credential variables (not the region).
 
 ### AWS CLI not found
 
-`switch-profile` requires AWS CLI v2. Install it for your platform:
+**macOS:** `brew install awscli`
 
-**macOS:**
-```shell
-brew install awscli
-brew link --overwrite awscli
-```
+**Linux and Windows:** follow the [AWS CLI install guide](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html).
 
-**Linux:**
-```shell
-curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"
-unzip awscliv2.zip
-sudo ./aws/install
-```
+## Documentation
 
-**Windows:** Download and run the [AWS CLI MSI installer](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html).
+<!-- BEGIN doc-index -->
+- [Architecture](docs/architecture.md) — Module map, data flow and bundling of the switch-profile CLI.
+- [AWS Profile Management](docs/aws-profile-management.md) — Profile kinds, switching, SSO logins, SSO import, migrations and the sp shell function.
+- [CLI Interface](docs/cli-interface.md) — Walkthrough of every command and screen of the CLI.
+- [Configuration Files](docs/configuration-files.md) — Exact formats of the AWS files, the settings file and the shell block written by switch-profile.
+- [Development Guide](docs/development-guide.md) — Build, lint, tests, manual testing and releases.
+- [Gotchas](docs/gotchas.md) — Non-obvious pitfalls for users and maintainers.
+<!-- END doc-index -->
 
 ## License