awx

Blazingly Fast AWS Profile & EKS Context Switcher

Overview

awx is a minimal Bash CLI to streamline AWS profile switching and EKS kubeconfig management for multi-account AWS setups. It supports both SSO-based and static credential profiles transparently.

Features

• Fuzzy, interactive AWS profile selection via fzf but also non-interactive mode: awx use --profile X --cluster Y for scripts and automation
• Toggle back to the previous AWS profile and EKS cluster with awx - (like cd -)
• Switch between existing kubeconfig contexts interactively with awx ctx
• Zsh tab completion for commands, subcommands, and AWS profile names
• Automatic SSO session re-authentication on every profile switch: if your session expires mid-day, awx detects it and re-authenticates transparently, with graceful fallback to static credentials when SSO fails
• EKS kubeconfig management with caching that skips redundant updates when the target context already exists
• Lists all configured AWS profiles with ACTIVE/EXPIRED session status and remaining SSO session lifetime via awx profiles
• Display the active profile, region, and EKS cluster with awx current
• Reset environment and clear cached data with awx clear
• Force refresh of SSO session with awx refresh

Usage

awx is a versatile script for managing AWS profiles and EKS kubeconfig contexts. Below are the primary commands and their purposes:

# Interactive mode (prompts with fuzzy finder)
awx                                          # Select AWS profile and cluster
awx use                                      # Same as awx
awx profile-name                             # Shortcut: set profile, then select cluster

# Non-interactive mode (for scripts and automation)
awx use --profile my-profile                 # Set profile without prompts
awx use --profile my-profile --cluster myc   # Fully non-interactive
awx --profile my-profile                     # Top-level flag (equivalent to above)

# Other commands
awx whoami                                   # Show current AWS identity
awx current                                  # Show current profile, region, and cluster
awx clear                                    # Unset AWS env vars and clear cache/state
awx refresh                                  # Force refresh of SSO session
awx eks list                                 # List available EKS clusters for active profile
awx eks update                               # Update kubeconfig for a specific cluster
awx ctx                                      # Switch kubeconfig context via fzf
awx help or -h                               # Show detailed usage instructions
awx logout                                   # Logout of the current AWS SSO session
awx profiles                                 # List all configured AWS profiles with ACTIVE/EXPIRED status and remaining session time
awx update                                   # Update awx to the latest version from GitHub

Example Workflow

$ awx
[INFO] Using profile: client-A (region: eu-central-1)
[INFO] Updating kubeconfig for cluster: cluster1-client-A
[INFO] Kubeconfig updated successfully

# On a repeated call when the context already exists:
$ awx
[INFO] Using profile: client-A (region: eu-central-1)
[INFO] Kubeconfig context already exists for cluster: cluster1-client-A, switching to context: client-A

Installation

Quick Install (recommended)

Install awx with a single command:

curl -sSL https://raw.githubusercontent.com/cschindlbeck/awx/main/install.sh | bash

The script will:

• Download awx to ~/.local/bin/awx
• Add a source line to your shell config (~/.zshrc or ~/.bashrc)
• Auto-install Zsh completions if Oh My Zsh is detected

Then reload your shell and verify:

source ~/.zshrc   # or ~/.bashrc
awx help

To update awx at any time after installation:

awx update

Environment overrides (all optional):

Variable	Default	Purpose
INSTALL_DIR	~/.local/bin	Directory to install the awx script
SHELL_RC	auto-detected	Shell config file to add the source line to
COMPLETIONS_DIR	auto-detected	Directory for Zsh completion file
BRANCH	main	GitHub branch to fetch from
NO_MODIFY_SHELL_RC	false	Set to true to skip shell config modification

Example: install to a custom directory without modifying the shell config:

INSTALL_DIR=~/bin NO_MODIFY_SHELL_RC=true \
  curl -sSL https://raw.githubusercontent.com/cschindlbeck/awx/main/install.sh | bash

Manual Install

1. Install Dependencies

• AWS CLI
• fzf
• jq
• kubectl (optional but recommended — enables fast context switching without a full aws eks update-kubeconfig call)

2. Clone and Set Up

git clone https://github.com/cschindlbeck/awx.git
cd awx

# Step 1: Install via make (symlinks awx to ~/.local/bin)
make install

# Step 2: Add to your shell config (~/.zshrc or ~/.bashrc)
# This is REQUIRED so that AWS_PROFILE persists in your shell session
source "$HOME/.local/bin/awx"

# Then reload your shell
source ~/.zshrc   # or ~/.bashrc

# (Optional) Install with oh-my-zsh
# ln -s $(pwd)/awx ~/.oh-my-zsh/custom/awx.zsh

Why sourcing is required: awx needs to run in your shell's current process to modify environment variables like AWS_PROFILE. If executed as a subprocess (without sourcing), any environment changes are lost when the process exits. Sourcing the script defines the awx() function in your current shell, making your AWS profile switches persist.

3. Shell Completion (Zsh)

Tab-completes commands, subcommands, and AWS profile names.

Plain zsh (add to ~/.zshrc):

fpath=(/path/to/awx/completions $fpath)
autoload -Uz compinit && compinit

Oh My Zsh:

mkdir -p ~/.oh-my-zsh/completions
cp completions/_awx ~/.oh-my-zsh/completions/
# Restart your shell or run: exec zsh

Testing and Quality

This project uses automated tests and pre-commit hooks that run in CI to ensure code quality and correct behavior. All contributors should run both locally before pushing or submitting a pull request.

A Makefile provides a single, discoverable interface for the most common development workflows:

Command	Description
make help	List all available targets
make test	Run all bats tests
make lint	Run pre-commit hooks on all files
make check	Run tests and lint
make install	Symlink awx to ~/.local/bin
make dev	Check development dependency status
make clean	Remove pre-commit cache and temp files

1. Automated Tests (bats)

• The main suite is written in bats-core. To use:

  On macOS:

  brew install bats-core

  On Linux/other platforms (manual install):

  curl -fsSL https://github.com/bats-core/bats-core/archive/refs/heads/master.zip -o bats.zip
  unzip bats.zip && cd bats-core-master && ./install.sh ~/bats-local && cd ..
  rm -rf bats.zip bats-core-master
  export PATH=$HOME/bats-local/bin:$PATH

• To run all tests via Make:

  make test

• Or run bats directly:

  bats tests

• Run an individual test file:

  bats tests/whoami.bats

Sample bats output:

1..4
ok 1 awx whoami with valid AWS_PROFILE
not ok 2 awx whoami with missing AWS_PROFILE
...

2. Pre-commit Hooks

Automated quality checks, formatting, and linting are enforced by pre-commit.

• To run pre-commit hooks via Make:

  make lint

• Or run pre-commit directly:

  pre-commit run --all-files

• These hooks run automatically on commit/pull request via GitHub Actions. You must pass these checks for your contributions to be accepted.

Best practice: Always run make check before committing or opening a PR.

Tips & Behavior

• If required tools (aws, fzf, or jq) are missing, awx will tell you exactly what to install.
• kubectl is an optional but recommended dependency. When present, awx skips aws eks update-kubeconfig if the target context (named after the profile) already exists in your kubeconfig, and instead calls kubectl config use-context directly — significantly reducing latency on repeated calls. Without kubectl, a full aws eks update-kubeconfig is always run.
• kubeconfig is updated per profile; back up your old file if you need persistent custom setups.
• Credential detection is automatic: awx checks for sso_start_url to detect SSO profiles and aws_access_key_id for static credentials. No manual configuration required.
• If a profile has both SSO and static credentials configured, SSO is attempted first. On SSO failure, awx falls back to static credentials automatically.
• Defaults to region from AWS_REGION, falling back to eu-central-1 if unset.
• EKS cluster results are cached per profile under $XDG_CACHE_HOME/awx/ (falls back to ~/.cache/awx/). The default TTL is 8 hours (480 minutes) and can be overridden with AWX_CACHE_TTL=<minutes>.

Contributing

Contributions, issues, and PRs are welcome!

To develop locally:

1. Fork & clone.
2. Install dependencies (see above).
3. Run make dev to verify your local toolchain.
4. Make changes on a new branch.
5. Run make check before opening a PR (runs tests and lint together).