awsp — AWS profile switcher

Tiny cross-shell function to switch AWS profiles (with SSO auto-login if needed).

• Works in Bash, Zsh and PowerShell (Windows PowerShell 5.1 / PowerShell 7+).
• No fzf dependency — numbered picker when no profile is passed.
• Extras: list profiles, show current, unset env, force login, verify identity (table/json).

Install

Platform	Method	Command
macOS / Linux	Homebrew	brew tap ops4life/awsp && brew trust ops4life/awsp && brew install awsp
macOS / Linux / WSL	install script	curl -fsSL https://raw.githubusercontent.com/ops4life/awsp/main/install.sh | sh
Windows (PowerShell)	install script	irm https://raw.githubusercontent.com/ops4life/awsp/main/install.ps1 | iex
Windows	Chocolatey	choco install awsp --params "/Profile"
Debian / Ubuntu	.deb from Releases	sudo dpkg -i awsp_<version>_all.deb
Any	from source	git clone https://github.com/ops4life/awsp.git && cd awsp && make install

Recent Homebrew versions refuse to load formulae from a tap you have not trusted, so the install needs the brew trust step. If your Homebrew has no brew trust command, skip it.

awsp is a shell function, so a package can only install the files — your shell must source them. After installing, add the matching line to ~/.bashrc / ~/.zshrc (the install script and make install do this for you):

# Homebrew
[ -f "$(brew --prefix)/share/awsp/awsp.sh" ] && . "$(brew --prefix)/share/awsp/awsp.sh"
# .deb
[ -f /usr/share/awsp/awsp.sh ] && . /usr/share/awsp/awsp.sh

The install script, make install and install.ps1 run preflight checks first (shell, required tools, AWS CLI v2, AWS profile files). Missing tools abort the install; a missing AWS CLI or profile only warns. Set AWSP_SKIP_PREFLIGHT=1 to skip them.

Upgrade with the same tool you installed with (brew upgrade awsp, re-run the install script, or install the newer .deb). On Windows, use the PowerShell installer above (WSL and Git Bash use the POSIX install script). The Chocolatey package leaves your profile alone unless you pass /Profile (it then edits the all-users PowerShell profiles); otherwise add . "$env:ChocolateyInstall\lib\awsp\tools\awsp.ps1" to your $PROFILE. If PowerShell blocks your profile, run Set-ExecutionPolicy -Scope CurrentUser RemoteSigned once. Uninstall with $env:AWSP_UNINSTALL=1; irm https://raw.githubusercontent.com/ops4life/awsp/main/install.ps1 | iex.

Plugin managers (zsh)

# zinit
zinit ice pick"bin/awsp.sh"
zinit light ops4life/awsp

# antidote (~/.zsh_plugins.txt)
ops4life/awsp path:bin/awsp.sh kind:source

# oh-my-zsh
git clone https://github.com/ops4life/awsp ~/.oh-my-zsh/custom/plugins/awsp
echo 'source ~/.oh-my-zsh/custom/plugins/awsp/bin/awsp.sh' >> ~/.zshrc

Uninstall

awsp --uninstall   # or: make uninstall

Removes all installed files and cleans up shell rc file entries. Homebrew and .deb installs print the package-manager command instead; a git checkout is never deleted.

Usage

Quick Start

Switch to a profile by name:

awsp my-profile-name

Or run without arguments to get an interactive numbered picker:

awsp
# Pick an AWS profile:
#  1) dev-account
#  2) staging-account
#  3) prod-account
# Select number: 2

Command Reference

awsp [options] [PROFILE]

Options:
  -h, --help         Show help and exit
  -V, --version      Show version and exit
  -l, --list         List profiles and exit
  -c, --current      Print current AWS profile and exit
  -u, --unset        Unset AWS profile & static creds and exit
  -U, --upgrade      Upgrade awsp to latest version
      --uninstall    Remove awsp and its rc file entries (asks first)
  -a, --add          Add a new profile (SSO or static credentials) and switch to it
  -r, --remove       Remove a profile (prompts for selection if omitted)
  -m, --modify       Modify/reconfigure an existing profile (prompts if omitted)
  -L, --login        Force "aws sso login" for the selected/current profile
  -v, --verify       Verify identity via STS (default: auto)
      --no-verify    Do not verify identity
      --json         Output STS identity as JSON instead of table
  -q, --quiet        Suppress non-essential output

Examples

List all available profiles:

awsp -l

Switch to a specific profile:

awsp dev-admin

Force SSO login for a profile:

awsp -L prod

Verify identity and show in JSON format:

awsp -v qa --json

Show current profile:

awsp -c

Unset all AWS environment variables:

awsp -u

Quiet mode (minimal output):

awsp -q prod

Show version:

awsp --version

Upgrade to latest version:

awsp --upgrade

awsp prints a one-line hint when a newer release exists, checked at most once a day (cached in ~/.config/awsp/update_check). Skip it with -q, or disable it with export AWSP_NO_UPDATE_CHECK=1.

Shell Completion

Zsh: Tab completion is automatically enabled after installation. Press <TAB> after typing awsp to complete profile names and options.

awsp <TAB>           # completes with available profile names
awsp -<TAB>          # completes with available options

Bash: Tab completion is automatically enabled after installation and works similarly.

Troubleshooting

Completion not working?

For Zsh, verify the completion function is loaded:

type _awsp
# Should output: _awsp is a shell function from /home/user/.config/awsp/completions/_awsp

If completion still doesn't work:

1. Make sure you've reloaded your shell after installation
2. Try sourcing the script manually: . "$HOME/.config/awsp/awsp.sh"
3. Check that the completions directory is in your fpath: echo $fpath | grep awsp

No profiles found?

Make sure you have at least one AWS profile configured:

aws configure sso
# or manually edit ~/.aws/config and ~/.aws/credentials

Requirements

• AWS CLI v2 (recommended, but will work without it for basic profile switching)
• At least one SSO profile configured: aws configure sso

How It Works

1. Profile Discovery: Reads profiles from aws configure list-profiles or parses ~/.aws/config and ~/.aws/credentials
2. Environment Setup: Exports AWS_PROFILE and AWS_DEFAULT_PROFILE, clears static credentials
3. SSO Auto-Login: Automatically runs aws sso login if credentials are expired (when AWS CLI is available)
4. Identity Verification: Optionally verifies your identity via aws sts get-caller-identity

Sequence Diagram(s)

Complete Profile Switching Flow

sequenceDiagram
    actor User
    participant awsp as awsp function
    participant AwsConfig as ~/.aws/config
    participant AwsCreds as ~/.aws/credentials
    participant Storage as ~/.config/awsp/
    participant AWS as AWS CLI/STS

    User->>awsp: awsp [profile]

    Note over awsp: Phase 1: Profile Selection
    alt No profile provided
        awsp->>AWS: aws configure list-profiles
        AWS->>awsp: Profile list
        awsp->>User: Show numbered picker
        User->>awsp: Select profile number
    else Profile name provided
        Note over awsp: Use provided profile name
    end

    Note over awsp: Phase 2: Environment Setup
    awsp->>awsp: Unset AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN
    awsp->>awsp: Unset AWS_PROFILE, AWS_DEFAULT_PROFILE
    awsp->>awsp: Export AWS_SDK_LOAD_CONFIG=1
    awsp->>awsp: Export AWS_PROFILE, AWS_DEFAULT_PROFILE
    awsp->>User: → Switched to [profile]

    Note over awsp,AwsConfig: Phase 3: SSO Detection
    awsp->>AwsConfig: Read profile config
    AwsConfig->>awsp: Profile settings
    awsp->>awsp: Check for SSO keys (sso_start_url, etc.)

    alt Profile is SSO-based
        Note over awsp,AwsCreds: Phase 4: Static Credential Management
        awsp->>AwsCreds: Check for static credentials
        alt Static credentials found
            awsp->>AwsCreds: Create backup
            awsp->>AwsCreds: Comment out static credentials
            awsp->>User: → Disabled static credentials (backup created)
        end
    end

    Note over awsp,Storage: Phase 5: Profile Persistence
    awsp->>Storage: Save profile to current_profile
    Note over Storage: Enables auto-load on next shell startup

    Note over awsp,AWS: Phase 6: Authentication & Verification
    alt Force login (-L flag)
        awsp->>User: Authenticating SSO...
        awsp->>AWS: aws sso login --profile [profile]
        AWS->>awsp: Login complete
    end

    alt Verify mode: on (-v) or auto (default)
        awsp->>AWS: aws sts get-caller-identity
        alt Credentials valid
            AWS->>awsp: Identity info
        else Credentials expired (auto mode only)
            awsp->>User: Authenticating SSO...
            awsp->>AWS: aws sso login --profile [profile]
            AWS->>awsp: Login complete
            awsp->>AWS: aws sts get-caller-identity (retry)
            AWS->>awsp: Identity info
        end
        alt --json flag
            awsp->>User: Display identity (JSON)
        else Default
            awsp->>User: Display identity (table)
        end
    else Verify mode: off (--no-verify)
        Note over awsp: Skip verification
    end

Loading

Quick Actions Flow

For reference, quick actions (--list, --current, --unset) bypass the full flow:

• awsp --list: Lists all profiles from AWS CLI or config files
• awsp --current: Prints current AWS_PROFILE value
• awsp --unset: Unsets all AWS environment variables and removes saved profile

License

This repository is licensed under the MIT License. See the LICENSE file for more information.