AWS Assume Role CLI

A fast, reliable command-line tool for switching between AWS IAM roles across different accounts. Built for modern development workflows with comprehensive multi-platform support.

✨ Key Features

• 🔄 Instant role switching between AWS accounts with simple commands
• 🔐 Smart credential management with automatic region and session handling
• 🌍 Multi-platform support (Linux, macOS Apple Silicon, Windows Git Bash)
• 📋 Multiple output formats (shell exports, JSON, environment variables)
• 💾 Persistent configuration with intuitive JSON storage
• ⏱️ Flexible session control with custom durations and automatic refresh
• 🧪 Battle-tested reliability (60 comprehensive tests across all platforms)
• 🚀 Zero-config installation via popular package managers

🚀 Quick Start

Installation

Choose your preferred method:

# 🍺 Homebrew (macOS/Linux) - Recommended
brew tap holdennguyen/tap && brew install aws-assume-role

# 🦀 Cargo (Rust users)
cargo install aws-assume-role

# 📦 Direct download (any platform)
curl -L https://github.com/holdennguyen/aws-assume-role/releases/download/v1.3.0/aws-assume-role-cli-v1.3.0.zip -o aws-assume-role-cli-v1.3.0.zip
unzip aws-assume-role-cli-v1.3.0.zip && cd aws-assume-role-cli-v1.3.0
./INSTALL.sh

📋 Need help with installation? → Complete Installation Guide

Basic Usage

# 1. Configure your first role
awsr configure --name dev --role-arn arn:aws:iam::123456789012:role/DevRole --account-id 123456789012

# 2. Verify it worked by checking your AWS identity
aws sts get-caller-identity

Essential Commands

💡 Shell Integration

Make role switching even faster with aliases:

# Add to ~/.bashrc, ~/.zshrc, or your shell config
alias assume-dev='awsr assume dev'
alias assume-prod='awsr assume prod'
alias aws-whoami='aws sts get-caller-identity --query "Arn" --output text'

# Usage
assume-dev      # Switch to dev role
aws-whoami      # Check current identity

📚 Documentation

🔧 Configuration

• 📁 Config Location: ~/.aws-assume-role/config.json
• 📝 Format: Human-readable JSON with role definitions
• 🔄 Auto-Creation: Created automatically when you configure your first role
• 🔒 Permissions: Automatically secured with appropriate file permissions

Example configuration:

{
  "roles": {
    "dev": {
      "role_arn": "arn:aws:iam::123456789012:role/DevRole",
      "account_id": "123456789012",
      "region": "us-east-1"
    },
    "prod": {
      "role_arn": "arn:aws:iam::987654321098:role/ProdRole",
      "account_id": "987654321098",
      "region": "us-west-2"
    }
  },
  "default_duration": 3600,
  "default_region": "us-east-1"
}

🛡️ Security & Compliance

• 🔐 Modern Cryptography: AWS SDK v1.x with aws-lc-rs backend
• 🛡️ FIPS Ready: Optional FIPS 140-3 compliance support
• 🔍 Security Audited: Clean security audit with zero known vulnerabilities
• 📋 Enterprise Features: Audit logging, centralized configuration, policy compliance

📦 Distribution & Availability

🚀 Getting Started for Different Users

👨‍💻 For Developers

1. Quick Setup: Follow the Quick Start above
2. Shell Integration: Add aliases for your most-used roles
3. IDE Integration: Configure your IDE to use assumed role credentials
4. Troubleshooting: Check our Development Guide for common issues

🏢 For DevOps Teams

1. Enterprise Installation: See Deployment Guide
2. Centralized Configuration: Set up organization-wide role definitions
3. CI/CD Integration: Use in your automated pipelines
4. Monitoring: Set up audit logging and usage monitoring

🔧 For Contributors

1. Development Setup: Follow the Development Guide
2. Testing: Run our comprehensive test suite (cargo test)
3. Contributing: Submit PRs following our development workflow
4. Release Process: Maintainers see our Safe Release Process

🎯 Why Choose AWS Assume Role CLI?

Before (Traditional AWS CLI)

# Complex, error-prone, hard to remember
aws sts assume-role \
  --role-arn "arn:aws:iam::123456789012:role/DevRole" \
  --role-session-name "my-session-$(date +%s)" \
  --duration-seconds 3600 \
  --query 'Credentials.[AccessKeyId,SecretAccessKey,SessionToken]' \
  --output text | while read access_key secret_key session_token; do
    export AWS_ACCESS_KEY_ID="$access_key"
    export AWS_SECRET_ACCESS_KEY="$secret_key"
    export AWS_SESSION_TOKEN="$session_token"
  done

After (AWS Assume Role CLI)

# Simple, reliable, memorable
awsr assume dev

🎉 Result: 10x faster role switching, zero errors, works everywhere!

🤝 Contributing

We welcome contributions! Here's how to get started:

1. 📖 Read the Development Guide: docs/DEVELOPER_WORKFLOW.md
2. 🧪 Run Tests: cargo test (all 60 tests must pass)
3. 🚀 Submit Changes: Follow our git flow workflow as described in the development guide.

Quick development setup:

git clone https://github.com/holdennguyen/aws-assume-role.git
cd aws-assume-role
./dev-cli.sh check  # Run all quality checks
./target/release/aws-assume-role --help

📊 Project Stats

• 🧪 Test Coverage: 60 comprehensive tests (unit, integration, additional)
• 🌍 Platform Support: Linux, macOS, Windows (100% test pass rate)
• 🔐 Security: Zero known vulnerabilities, modern cryptography
• 📦 Distribution: 6+ installation methods, automated CI/CD
• ⚡ Performance: Sub-second role switching, minimal resource usage

📄 License

This project is licensed under the GNU AGPLv3 - see the LICENSE file for details.

🙏 Acknowledgments

Built with the modern Rust ecosystem and AWS SDK v1.x for reliable, secure AWS credential management. Special thanks to the AWS CLI team for providing the foundation this tool builds upon.

💡 Need Help?

• 📖 Documentation: Start with docs/DEPLOYMENT.md for installation
• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions
• 📧 Contact: Create an issue for support