awsctx

awsctx is a Go CLI similar to kubectx, built to switch AWS CLI profiles quickly.

It supports:

• Plain profiles from ~/.aws/credentials
• SSO profiles from ~/.aws/config
• Interactive selection through fzf
• Local awsctx settings customization
• Writing/updating static and SSO profiles securely

Build from source

go build -o bin/awsctx ./cmd/awsctx

Install from source

mkdir -p "$HOME/.local/bin"
cp bin/awsctx "$HOME/.local/bin/awsctx"

Add to PATH (zsh):

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Install from GitHub Releases

Download the latest binary for your platform, then move it into your PATH.

macOS (Apple Silicon)

curl -L -o /tmp/awsctx https://github.com/kjvjobin/awsctx/releases/latest/download/awsctx_darwin_arm64
chmod +x /tmp/awsctx
sudo mv /tmp/awsctx /usr/local/bin/awsctx

macOS (Intel)

curl -L -o /tmp/awsctx https://github.com/kjvjobin/awsctx/releases/latest/download/awsctx_darwin_amd64
chmod +x /tmp/awsctx
sudo mv /tmp/awsctx /usr/local/bin/awsctx

Linux (x86_64)

curl -L -o /tmp/awsctx https://github.com/kjvjobin/awsctx/releases/latest/download/awsctx_linux_amd64
chmod +x /tmp/awsctx
sudo mv /tmp/awsctx /usr/local/bin/awsctx

Verify install:

awsctx --help

Then enable shell integration:

awsctx init zsh --write
source ~/.zshrc

Commands

awsctx list
awsctx current
awsctx use <profile>
awsctx use <profile> --login
awsctx toggle
awsctx fzf
awsctx env
awsctx settings
awsctx init zsh
awsctx configure static ...
awsctx configure sso ...

Shell integration

Install zsh integration once:

awsctx init zsh --write
source ~/.zshrc

Preview the snippet before writing:

awsctx init zsh

If you run from the repo binary directly:

bin/awsctx init zsh --write
source ~/.zshrc

Verify:

awsctx use sandbox
echo "$AWS_PROFILE"
aws sts get-caller-identity

Login on demand for SSO profiles:

awsctx use sandbox --login

Configure awsctx behavior

Show current settings:

awsctx settings

Update paths or fzf command:

awsctx settings \
  --credentials-file ~/.aws/credentials \
  --aws-config-file ~/.aws/config \
  --state-file ~/.config/awsctx/state.json \
  --fzf-command "fzf --height 40%"

Enable auto SSO login during use, toggle, and fzf profile switches:

awsctx settings --auto-sso-login true

Configure profile entries

Static credentials profile

awsctx configure static \
  --profile dev \
  --access-key-id AKIA... \
  --secret-access-key ... \
  --region us-east-1

SSO profile

awsctx configure sso \
  --profile engineering \
  --sso-start-url https://example.awsapps.com/start \
  --sso-region us-east-1 \
  --sso-account-id 123456789012 \
  --sso-role-name Admin \
  --region us-east-1

Security notes

• awsctx uses strict file permissions (0700 dirs, 0600 files) for its own state/config and rewritten AWS files.
• Writes are atomic (temp file + rename) to reduce corruption risk.
• awsctx use validates profile names from AWS files before activation.
• Avoid passing secrets on CLI in shared environments because shell history may capture them; prefer env vars or prompt input.

Limitations

• This tool rewrites INI files and does not preserve comments/order.