kee 1.4.2

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
  • 🌐 Open the console: kee console opens the AWS Management Console in your browser for the chosen profile
  • 📝 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.86+ (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.

Open the AWS Management Console

kee console                # Use the active session, or pick interactively
kee console PROFILE_NAME   # Open the console for a specific profile

Federates your temporary credentials with AWS and opens the console in your default browser, already signed in to the chosen account and role. No more flipping accounts in the console picker.

The destination region matches the profile's SSO region. You can navigate to other regions from inside the console as usual.

Requires AWS CLI v2.15+ (which provides aws configure export-credentials).

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.