kee 1.3.0

AWS CLI profile manager
Documentation

Tests Latest version LicenseOSX Linux Windows

A simple tool to help you manage multiple AWS profiles, with SSO support and easy account access.

Features

  • 🔐 SSO integration: Full support for AWS SSO authentication
  • 🚀 Easy profile access: Use any configured profile with a single command
  • 🎯 Interactive picker: Run kee use with no arguments to pick a profile with fuzzy search
  • 🐚 Sub-shell isolation: Each profile runs in its own sub-shell with proper credential isolation
  • ⚙️ One-shot commands: Run a single command with a profile's credentials via kee run or kee aws
  • 📝 Custom aliases: Use friendly names for your AWS profiles
  • 🔍 Profile management: Easily list, add, update, and remove profiles
  • 🚫 No stored credentials: No AWS credentials are stored anywhere - uses AWS SSO tokens
  • 🎨 Shell integration: Shows current profile in your shell prompt
  • ⚡ Auto-refresh: Proactively refreshes tokens on every use and keeps sessions alive in the background
  • 🚨 Production safety: Mark accounts as production to get a visible warning banner

Security notes

  • No credential storage: Kee never stores AWS access keys or secrets
  • SSO token management: Uses AWS CLI's built-in SSO token caching
  • Sub-shell isolation: Each profile's session is isolated in its own shell
  • Automatic cleanup: Environment variables are cleared when exiting sub-shells

Why Rust?

  • 🚀 Performance: Compiled binary, faster startup times
  • ⛑️ Memory safety: No runtime errors, guaranteed memory safety
  • 🌍 Cross-platform: Single binary works across platforms
  • 👌 Zero dependencies: No Python runtime required
  • ⚡️ Concurrent: Built-in concurrency support for future enhancements

Installation

Prerequisites

  • Rust 1.80+ (install from rustup.rs) (On Mac with brew: brew install rust)
  • AWS CLI v2 installed and configured
  • Configured AWS SSO account access

Install from crates.io

cargo install kee

Install from source

Clone this repository:

git clone https://github.com/keecli/kee.rs.git ~/.kee

Option 1: Automated (recommended)

cd ~/.kee
./install.sh

This script will build an optimized Kee binary, install it (in ~/.cargo/bin), and add the folder to your PATH. It will also install Kee's auto completions.

Option 2: Manual

cd ~/.kee

# Install the binary
cargo install --path .

# Add Cargo's bin directory to your PATH
echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.zshrc  # For zsh (macOS default)
# OR
echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.bashrc  # For bash

# Reload your shell configuration
source ~/.zshrc  # or ~/.bashrc

Option 3: Direct copy

cd ~/.kee

# Build and copy to a directory already in PATH
cargo build --release
cp target/release/kee ~/.local/bin/  # Make sure ~/.local/bin is in your PATH

Quick Start

1. Add your first profile

kee add mycompany.dev

This will:

  • Run aws configure sso --profile company.dev
  • Prompt you for your SSO configuration (start URL, region, etc.)
  • Open your browser for SSO authentication
  • Let you select your AWS account and role interactively
  • Automatically save the configuration to Kee

Tip: A session can be liked to multiple profiles. When prompted for a 'session name', use something generic, like your company name.

2. Use a profile

Pick interactively:

kee use

Or jump straight to one by name:

kee use mycompany.dev

Either path will:

  • Check if SSO credentials are valid
  • Automatically run aws sso login if needed
  • Start a sub-shell with AWS credentials configured
  • Update your shell prompt to show the active profile

3. Work with AWS

Inside the sub-shell, all AWS CLI commands will use the selected profile's credentials:

aws:mycompany.dev $ aws s3 ls
aws:mycompany.dev $ aws ec2 describe-instances
aws:mycompany.dev $ exit  # Terminate the session and return to your main shell

Commands

Show status or help

kee

With no arguments, Kee shows the current active profile if you are inside a session, or prints help text otherwise.

Add a profile

kee add PROFILE_NAME

Interactively configure a new AWS profile with SSO settings. You'll be asked whether this is a production account — production profiles display a warning banner when active.

Use a profile

kee use                # Pick interactively with fuzzy search
kee use PROFILE_NAME   # Skip the picker

Use a profile and start a sub-shell with its AWS credentials. With no name, Kee opens a fuzzy picker over your configured profiles. Every kee use proactively refreshes the token to give you the maximum session window.

Run a single command

Use kee aws for AWS CLI commands (the common case):

kee aws PROFILE_NAME ARGS...

kee aws mycompany.dev s3 ls
kee aws mycompany.dev sts get-caller-identity

For anything else, use kee run:

kee run PROFILE_NAME -- CMD ARGS...

kee run mycompany.dev -- terraform plan
kee run mycompany.dev -- ./deploy.sh
kee run mycompany.dev -- aws s3 ls    # works too, just longer

Both run a single command with the profile's credentials and exit. No sub-shell, no prompt change. The wrapped command's exit code is propagated. Kee's own status messages go to stderr so they don't pollute the wrapped command's stdout. Production profiles still print a warning banner to stderr.

The -- separator in kee run is recommended any time the wrapped command starts with a flag, so Kee doesn't try to interpret it.

List all profiles

kee ls

Show a quick overview of all configured profiles.

Show current profile

kee current

Display which profile is currently active (if any).

Update profile settings

kee set PROFILE_NAME --production       # Mark as production
kee set PROFILE_NAME --no-production    # Unmark as production

Update settings for an existing profile.

Remove a profile

kee rm                 # Pick interactively
kee rm PROFILE_NAME    # Skip the picker

Removes a profile configuration from Kee and the AWS config file.

How It Works

Configuration storage

  • Kee stores its configuration in ~/.kee/config.json
  • AWS profiles are created in ~/.aws/config, following the AWS config pattern
  • No AWS credentials are stored - only SSO configuration

Sub-shell environment

When you use a profile, Kee:

  1. Validates SSO credentials (refreshes if needed)
  2. Updates shell prompt to show current profile
  3. Starts a new shell session
  4. Cleans up when you exit

Session management

When you run kee use, your session is refreshed proactively — every invocation gives you the maximum session window regardless of how much time was left.

While the sub-shell is active, a background process monitors the token's expiry and refreshes it automatically before it lapses. This means your session stays alive indefinitely as long as the sub-shell is open (limited only by the refresh token registration, typically ~3 months).

If the refresh token is expired or unavailable, Kee falls back to the full aws sso login flow.

 ⠹ Refreshing session...
 [✓] Session refreshed.

 Profile: mycompany.dev
 Kee is starting a sub-shell...
 Type exit to return to your main shell.

Kee also prevents you from starting a sub-shell while already in one:

aws:mycompany.dev $ kee use mycompany.prod

You are using a Kee profile: mycompany.dev
Exit the current session first by typing 'exit'

Shell prompt integration

Your shell prompt will show the active profile:

(mycompany.dev) user@hostname:

Production safety

Profiles marked as production display a bold red warning when you enter the sub-shell:

 ⚠️  PRODUCTION ACCOUNT

 Profile: mycompany.prod
 Kee is starting a sub-shell...
 Type exit to return to your main shell.

Mark a profile as production during kee add or at any time with kee set PROFILE_NAME --production.

Environment variables

When you're using a Kee profile, the following environment variables are set:

  • AWS_PROFILE - The AWS profile name (e.g., mycompany.dev)
  • KEE_CURRENT_PROFILE - The current Kee profile name (e.g., mycompany.dev)
  • KEE_ACTIVE_PROFILE - Set to 1 to indicate an active Kee profile
  • PS1 - Updated to show the current profile in your prompt (Unix-like systems only)

These variables help Kee manage sessions and prevent nested sub-shells.

Configuration files

Kee configuration (~/.kee/config.json)

{
  "profiles": {
    "mycompany-prod": {
      "profile_name": "mycompany.prod",
      "sso_start_url": "https://mycompany.awsapps.com/start",
      "sso_region": "ap-southeast-2",
      "sso_account_id": "123456789012",
      "sso_role_name": "AdministratorAccess",
      "session_name": "mycompany",
      "production": true
    }
  },
  "current_profile": null
}

AWS config (~/.aws/config)

[profile mycompany.dev]
sso_role_name = AdministratorAccess
sso_session = mycompany
sso_account_id = 123456789098
output = json

[sso-session mycompany]
sso_region = ap-southeast-2
sso_start_url = https://mycompany.awsapps.com/start
sso_registration_scopes = sso:account:access

Cross-platform support

Kee works on:

  • macOS: Full support with shell prompt integration
  • Linux: Full support with shell prompt integration
  • Windows: Full support (prompt integration not available)

Troubleshooting

SSO login issues

If SSO login fails:

# Manual SSO login
aws sso login --profile PROFILE_NAME

# Then try using again
kee use PROFILE_NAME

Profile not found

If you get "profile not found" errors:

# Check AWS config
cat ~/.aws/config

# Re-add the profile if needed
kee rm PROFILE_NAME
kee add PROFILE_NAME

Permission issues

If you get permission errors:

# Check AWS credentials
aws sts get-caller-identity --profile PROFILE_NAME

# Refresh SSO login
aws sso login --profile PROFILE_NAME

Future enhancements

  • Built-in AWS SDK integration (no AWS CLI dependency)
  • Configuration validation at compile time
  • Plugin system with dynamic loading
  • TUI interface with real-time updates

Binary distribution:

  • Single executable file
  • No runtime dependencies
  • Easy deployment to servers
  • Container-friendly

Package managers:

  • Cargo: cargo install kee
  • Homebrew: brew install kee (planned)
  • Scoop: scoop install kee (Windows, planned)
  • APT/YUM: Native packages possible (planned)

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Add tests, if applicable
  5. Test your changes: make test
  6. Submit a pull request

There is a utilities script which will set up a pre-commit hook to run some basic checks on your code before you commit.

cd ~/.kee
./utilities/githooks.sh

Versioning

We use semantic versioning. Version bumps are handled with cargo-release.

cargo install cargo-release

When your changes are ready:

cargo release patch   # Bug fixes:        1.1.0 → 1.1.1
cargo release minor   # New features:     1.1.0 → 1.2.0
cargo release major   # Breaking changes: 1.0.0 → 2.0.0

This updates Cargo.toml, commits, and tags in one step. Add --execute to apply (without it, it runs in dry-run mode).

License

MIT License - see LICENSE file for details.

Support

RTFM, then RTFC... If you are still stuck or just need an additional feature, file an issue.