<div align="center">
<img src="https://raw.githubusercontent.com/aichholzer/kee/refs/heads/main/kee.png" alt="Kee" />
</div>
[](https://github.com/aichholzer/kee/actions/workflows/test.yml)
[](https://codecov.io/gh/aichholzer/kee)
[](https://crates.io/crates/kee)
<br />
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
- ⚡️ **Concurrent**: Built-in concurrency support for future enhancements
## Installation
### Prerequisites
- Rust 1.86+ (install from [rustup.rs](https://rustup.rs/)) (On Mac with brew: `brew install rust`)
- AWS CLI v2 installed and configured
- Configured AWS SSO account access
### Install from crates.io
```bash
cargo install kee
```
After install, set up shell completions in one command:
```bash
kee completions install
```
This auto-detects your shell (bash, zsh, or fish), drops the script in
the right place, and edits your shell config to load it. Restart your
terminal or `source` the relevant rc file to pick up completions.
### Install from source
Clone this repository:
```bash
git clone https://github.com/keecli/kee.rs.git ~/.kee
```
**Option 1: Automated (recommended)**
```bash
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**
```bash
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**
```bash
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
```bash
kee add mycompany.dev
```
This will:
- Run `aws configure sso --profile mycompany.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:
```bash
kee use
```
Or jump straight to one by name:
```bash
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:
```bash
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
### Global flags
These flags work with any command:
- `-v`, `--verbose`: Print diagnostic detail to stderr (AWS CLI errors, refresh outcomes, cache parsing issues). Useful when something silently fails.
- `-V`, `--version`: Print the installed version and exit.
- `-h`, `--help`: Show help. Works on subcommands too (e.g., `kee use --help`).
### Show status or help
```bash
kee
```
With no arguments, Kee shows the current active profile if you are inside a session, or prints help text otherwise.
### Add a profile
```bash
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
```bash
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):
```bash
kee aws PROFILE_NAME ARGS...
```
```bash
kee aws mycompany.dev s3 ls
kee aws mycompany.dev sts get-caller-identity
```
For anything else, use `kee run`:
```bash
kee run PROFILE_NAME -- CMD ARGS...
```
```bash
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
```bash
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
```bash
kee ls # Pretty list
kee ls --names # Just the profile names, one per line (handy for scripting)
```
Show a quick overview of all configured profiles.
### Show profile status
```bash
kee status
```
Show detailed status of all profiles: session health (active/expired), token expiry countdown, account ID, account alias, and role. Checks run in parallel so the output appears quickly even with many profiles.
### Show current profile
```bash
kee current
```
Display which profile is currently active (if any).
### Update profile settings
```bash
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
```bash
kee rm # Pick interactively
kee rm PROFILE_NAME # Skip the picker
```
Removes a profile configuration from `Kee` and the AWS config file.
### Shell completions
```bash
kee completions install # Install for the current shell (auto-detected)
kee completions install --shell zsh # Install for a specific shell
kee completions uninstall # Remove for the current shell
kee completions print zsh # Print the script to stdout (no install)
```
Install drops the completion script in the right place and edits your shell config to load it. Supported: `bash`, `zsh`, `fish`. For `powershell` and `elvish`, use `print` and follow your shell's documentation. Edits are idempotent: re-running `install` is safe.
## 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:
```bash
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:
```bash
(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`)
```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`)
```ini
[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:
```bash
# 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:
```bash
# 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:
```bash
# 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)
- **Plugin system** with dynamic loading
**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.
```bash
cd ~/.kee
./utilities/githooks.sh
```
### Test coverage
CI runs [`cargo-llvm-cov`](https://github.com/taiki-e/cargo-llvm-cov) on Linux and reports line coverage to Codecov. There is no hard threshold: it's a signal to track over time, not a gate.
To check locally:
```bash
cargo install cargo-llvm-cov
cargo llvm-cov --all-targets
```
`cargo-llvm-cov` uses LLVM source-based coverage, which traces cleanly into binaries spawned by `assert_cmd` in `tests/cli_tests.rs`. We previously used `cargo-tarpaulin`, which relied on ptrace and was unstable for subprocess-heavy tests.
Coverage runs on Linux; macOS and Windows users can rely on CI for the report.
### Versioning
We use [semantic versioning](https://semver.org/). Version bumps are handled with [`cargo-release`](https://github.com/crate-ci/cargo-release).
```bash
cargo install cargo-release
```
When your changes are ready:
```bash
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](https://github.com/aichholzer/kee/issues).
<div align="center">
✌🏼
</div>
