awspss

AWS Identity Center Permission Sets Switcher

한국어

Interactively select an AWS Account and Permission Set after SSO login, and the temporary credentials are automatically set in your current shell.

Installation

pip / pipx

pip install awspss

# or pipx (isolated environment)
pipx install awspss

Homebrew

brew tap boseung-code/tap
brew install awspss

From source

git clone https://github.com/boseung-code/awspss.git
cd awspss
pip install -e .

Setup

1. Register shell function

Shell function registration is required for awspss login and awspss sw to set credentials directly in your current shell. This also enables Tab completion for commands.

eval "$(awspss init)"

This will:

1. Detect your shell rc file (.bashrc or .zshrc)
2. Ask for confirmation
3. Register to rc file + activate immediately in current shell

Duplicate registration is prevented. New terminals will activate automatically.

To register manually, add to your .bashrc or .zshrc:

eval "$(awspss init --print)"

2. Configure SSO connection

awspss configure

Prompts for start-url and region interactively. You can also pass them directly:

awspss configure --start-url https://your-org.awsapps.com/start --region ap-northeast-2

Usage

Login

awspss login

Always performs a fresh SSO authentication via browser. After authentication, select Account → Permission Set and credentials are set in your current shell. Credential expiration time is displayed after login.

Switch credentials

awspss sw

Switch to a different Account/Permission Set using cached token (no re-login). Automatically re-authenticates if the token has expired.

Quick switch (permission set only)

awspss sw AdministratorAccess

Switch to a different Permission Set within the same account without interactive selection. Tab completion is supported — press Tab after awspss sw to see available permission sets.

Check current identity

awspss whoami

Displays the current AWS identity (Account, ARN, UserId).

Without shell function (eval)

eval $(awspss login)
eval $(awspss sw)

Verify credentials

aws sts get-caller-identity
aws s3 ls
terraform plan

Clear credentials

awspss unset

Logout (clear cached token)

awspss logout

Removes the cached SSO token. Use this when you want to force a fresh login next time.

Commands

Command	Description
awspss init	Register shell function (auto-add to rc file + activate)
awspss init --print	Print shell function only (for manual setup)
awspss configure	Configure SSO connection
awspss login	SSO login (always re-authenticates)
awspss sw	Switch account/permission set (uses cached token)
awspss sw [ROLE]	Quick switch permission set (Tab completion supported)
awspss whoami	Show current AWS identity
awspss unset	Clear AWS credentials from current shell
awspss logout	Clear cached SSO token