┌───────────────────────┐       ┌────────────────────────┐       ┌───────────────────────┐
  │  IAM Identity Center  │ ────> │       aws-auth         │ ────> │  ~/.aws/credentials   │
  │     (AWS SSO OIDC)    │       │  (Smart Role Selector) │       │ (Strict 0600 POSIX)   │
  └───────────────────────┘       └───────────┬────────────┘       └───────────┬───────────┘
                                              │                                │
                                  ┌───────────▼────────────┐       ┌───────────▼───────────┐
                                  │   MCP Server (stdio)   │       │ Terraform / K8s / CLI │
                                  │ (Claude / Cursor / AI) │       │ (Instant Compatibility)│
                                  └────────────────────────┘       └───────────────────────┘

irm https://raw.githubusercontent.com/N0mansky/aws-auth/main/install.ps1 | iex

curl.exe -L https://github.com/N0mansky/aws-auth/releases/latest/download/aws-auth-windows-amd64.exe -o aws-auth.exe

curl -L https://github.com/N0mansky/aws-auth/releases/latest/download/aws-auth-linux-amd64 -o aws-auth
chmod +x aws-auth && sudo mv aws-auth /usr/local/bin/

curl -L https://github.com/N0mansky/aws-auth/releases/latest/download/aws-auth-macos-universal -o aws-auth
chmod +x aws-auth && sudo mv aws-auth /usr/local/bin/

git clone https://github.com/N0mansky/aws-auth.git
cd aws-auth

./install.sh                      # Linux / macOS / WSL2 (configures ~/.zshrc, ~/.bashrc)
powershell .\install.ps1          # Windows (PowerShell - configures $PROFILE)
.\install.bat                     # Windows (Command Prompt)

pip install git+https://github.com/N0mansky/aws-auth.git

# >>> aws-auth shell wrapper >>>
# Auto-export active profile on shell startup if present
if [ -f ~/.aws-auth/current_profile ]; then
    export AWS_PROFILE=$(< ~/.aws-auth/current_profile)
fi

# Scopes active profile to current terminal session via AWS_PROFILE
aws-auth() {
    command /usr/local/bin/aws-auth "$@"
    local ret=$?
    if [ $ret -eq 0 ] && [ -f ~/.aws-auth/current_profile ]; then
        export AWS_PROFILE=$(< ~/.aws-auth/current_profile)
    fi
    return $ret
}
# <<< aws-auth shell wrapper <<<

aws-auth

Available account-role combinations (Showing 1-10 of 18):
+-----+------------------------------+-----------------+------------------------------+-------------+
| #   | Account                      | Account ID      | Role                         | Region      |
+-----+------------------------------+-----------------+------------------------------+-------------+
| 1   | ⭐ Production-App (PROD)        | (111222333444)  | AdministratorAccess     | us-east-1   |
| 2   | ⭐ Staging-Web (QA)          | (555666777888)  | AdministratorAccess     | us-east-1   |
| 3   | Analytics-Data                  | (999888777666)  | AdministratorAccess     | us-east-1   |
...
Select number 1-10 (default: 1) (type keyword to filter): [ENTER]

✅ Profile 'production-app-admin' saved to ~/.aws/credentials.
✅ Active profile set to: production-app-admin (scoped via AWS_PROFILE)

aws-auth --configure

{
  "sso_start_url": "https://my-company.awsapps.com/start",
  "sso_region": "us-east-1",
  "preferred_accounts": ["Staging-Web", "Production-App"],
  "aliases": {
    "555666777888": "QA",
    "111222333444": "PROD"
  }
}

{
  "mcpServers": {
    "aws-auth": {
      "command": "aws-auth",
      "args": ["--mcp"]
    }
  }
}

# Core Authentication
aws-auth                     # Interactive SSO login & smart role switch
aws-auth --configure         # Interactive SSO portal setup
aws-auth --identity          # Show current STS caller identity
aws-auth --refresh-cache     # Force refresh remote account/role metadata
aws-auth --write-default     # Opt-in to write/sync credentials to [default] section

# Profile Management & Session Scoping
aws-auth --list-profiles          # List all stored AWS profiles (* marks active)
aws-auth --current-profile        # Print active profile name (fast query)
aws-auth -p, --use-profile NAME   # Activate named profile in current session
aws-auth -s, --switch-profile     # Interactive profile switcher
aws-auth --set-default NAME       # Copy profile credentials to [default] section
aws-auth --delete NAME            # Delete profile credentials

# Resource Discovery & DevOps
aws-auth --list-ec2          # List EC2 instances and connect via SSM
aws-auth --list-eks          # List EKS clusters and update kubeconfig

# Scripting & Headless Automation
aws-auth --current-profile --json # JSON output {"current_profile": "..."}
aws-auth --list-profiles --json
aws-auth --identity --json
eval $(aws-auth --export-env prod-profile)  # Export AWS keys to current shell

# AWS credential_process standard
aws-auth --credential-process my-profile

make help          # View all available targets
make venv          # Initialize virtual environment and install dev dependencies
make test          # Run automated unit tests with pytest
make check         # Run full quality gate (secret scanning, Bandit SAST, audit, tests)
make build         # Compile standalone PyInstaller binary