⚡ Fast • 🔐 Secure • 🤖 AI-Powered • 🌍 Bilingual

• ⚡ Lightning Fast: Search and switch between dozens of AWS profiles in milliseconds
• 🔐 SSO Made Easy: Automatic re-authentication when credentials expire - no manual login headaches
• 🤖 AI-Powered: Integrated Amazon Q Developer CLI for intelligent AWS assistance
• 🎯 Smart CLI: Command autocomplete with AWS CLI cheatsheet built-in
• 🌍 Bilingual: Full support for English and Traditional Chinese
• 📊 Clear Visibility: See profile details, account info, and current identity at a glance
• 🎨 Modern UX: Beautiful, keyboard-driven interface that respects your terminal theme

• Fast Profile Search: Filter by name, account, role, or region with real-time fuzzy matching
• SSO Authentication: Automatic aws sso login when tokens expire or on manual trigger
• Profile Details: View comprehensive profile information including account, role, region, and session

• Amazon Q Integration: Ask questions in natural language
• Context-Aware: Automatically includes your current profile and region
• Streaming Responses: Real-time output as Q processes your query
• Command Suggestions: Get AWS CLI commands for common tasks

• Command History: Browse previous commands with ↑↓
• Smart Autocomplete: Suggestions from AWS CLI cheatsheet
• Inline Execution: Run AWS CLI commands directly in the TUI
• Output Capture: See command results with timing and exit codes
• Built-in Cheatsheet: Quick reference for 15+ AWS services

• Structured Logging: JSON logs to STDERR for debugging and monitoring
• Cross-Platform: Linux, macOS, Windows (PowerShell)
• Keyboard-First: Efficient navigation without touching the mouse
• Extensible: Clean Python architecture for customization

# Install with uv (recommended)
uv tool install --python 3.13 awsui

# Or install with pip
pip install awsui

# Launch the TUI
awsui

That's it! Start managing your AWS profiles with ease. 🚀

• Python: >= 3.13, < 3.14
• AWS CLI: v2 (required)
• Amazon Q CLI: Optional, for AI assistance (installation guide)
• uv: Recommended for dependency management (installation guide)

# Install as a tool (isolated environment)
uv tool install --python 3.13 awsui

# Run directly
awsui

pip install awsui

# Run
awsui

# Clone the repository
git clone https://github.com/junminhong/awsui.git
cd awsui

# Pin Python version
uv python install 3.13
uv python pin 3.13

# Install dependencies
uv sync

# Run from source
uv run awsui

Launch the TUI to select and switch profiles:

awsui

Keyboard Shortcuts:

Skip interactive selection:

# Pre-select a profile when launching the TUI
awsui --profile my-prod-admin

Temporarily override AWS region:

awsui --profile my-profile --region us-west-2

# English (default)
awsui --lang en

# Traditional Chinese
awsui --lang zh-TW

awsui --log-level DEBUG 2> awsui-debug.log

1. Install Amazon Q Developer CLI:

   # Follow official installation guide
   # https://docs.aws.amazon.com/amazonq/latest/qdeveloper-ug/command-line-installing.html

2. Verify installation:

   q --version

1. Press a in awsui to open AI assistant panel
2. Type your question (e.g., "How do I list all S3 buckets with encryption enabled?")
3. Press Enter to submit
4. View streaming response with AWS-specific context
5. Press a again to close panel

The assistant automatically includes your current profile, region, and account context for more relevant answers.

~/.aws/config:

[sso-session my-company]
sso_start_url = https://my-company.awsapps.com/start
sso_region = us-east-1
sso_registration_scopes = sso:account:access

[profile production-admin]
sso_session = my-company
sso_account_id = 111111111111
sso_role_name = AdministratorAccess
region = us-east-1
output = json

[profile staging-developer]
sso_session = my-company
sso_account_id = 222222222222
sso_role_name = DeveloperAccess
region = us-west-2
output = json

[profile base]
region = us-east-1

[profile cross-account-admin]
source_profile = base
role_arn = arn:aws:iam::333333333333:role/AdminRole
region = us-east-1

[profile legacy-sso]
sso_start_url = https://my-company.awsapps.com/start
sso_region = us-east-1
sso_account_id = 444444444444
sso_role_name = ViewOnlyAccess
region = us-east-1

awsui/
├── awsui/                      # Main package
│   ├── __init__.py
│   ├── app.py                  # Main Textual application
│   ├── models.py               # Profile data models
│   ├── config.py               # AWS config parsing (~/.aws/config)
│   ├── aws_cli.py              # AWS CLI wrapper (SSO, STS)
│   ├── q_assistant.py          # Amazon Q Developer CLI integration
│   ├── autocomplete.py         # Command autocomplete engine
│   ├── command_parser.py       # AWS CLI command parser
│   ├── parameter_metadata.py   # AWS parameter metadata handling
│   ├── resource_suggester.py   # AWS resource suggestion engine
│   ├── service_model_loader.py # AWS service model loader
│   ├── cheatsheet.py           # AWS CLI command reference
│   ├── i18n.py                 # Internationalization (EN/ZH-TW)
│   └── logging.py              # Structured JSON logging
├── tests/                      # Test suite
│   ├── __init__.py
│   ├── conftest.py             # Pytest configuration
│   ├── test_app.py
│   ├── test_autocomplete.py
│   ├── test_aws_cli.py
│   ├── test_cheatsheet.py
│   ├── test_command_parser.py
│   ├── test_config.py
│   ├── test_global_parameters.py
│   ├── test_i18n.py
│   ├── test_logging.py
│   ├── test_models.py
│   ├── test_q_assistant.py
│   ├── test_resource_suggester.py
│   ├── test_service_model_loader.py
│   ├── test_special_commands.py
│   └── test_special_commands_no_autocomplete.py
├── docs/                       # Documentation website
│   ├── index.html
│   ├── styles.css
│   ├── script.js
│   └── images/                 # Documentation images
├── images/                     # README images
│   ├── logo.png
│   ├── demo01.png
│   ├── demo02.png
│   ├── demo03.png
│   └── demo04.png
├── pyproject.toml              # Project configuration
├── uv.lock                     # Dependency lock file
├── LICENSE                     # MIT License
├── README.md                   # English documentation
└── README_ZH_TW.md             # Traditional Chinese documentation

uv run pytest

uv run pytest --cov=awsui --cov-report=html
open htmlcov/index.html

uv sync --dev

# Linting (if configured)
uv run ruff check awsui/

# Type checking (if configured)
uv run mypy awsui/

aws --version  # Should show "aws-cli/2.x.x ..."

# For SSO
aws configure sso-session

# For legacy SSO
aws configure sso

# For static credentials
aws configure

# Try manual login first
aws sso login --profile your-profile-name

# Check browser permissions
# Ensure port 8080-8090 range is available for OAuth callback

# Force re-authentication
# Press 'l' in awsui to trigger SSO login

# Verify profile configuration
cat ~/.aws/config

# Test manually
aws sts get-caller-identity --profile your-profile-name

# macOS
brew install amazon-q

# Other platforms: follow official guide
# https://docs.aws.amazon.com/amazonq/latest/qdeveloper-ug/command-line-installing.html

q --version

awsui follows AWS security best practices:

• ✅ Credential Handling: Only uses AWS CLI's credential system - no credential storage or caching
• ✅ Temporary Credentials: Leverages AWS STS and SSO for short-lived tokens
• ✅ Read-Only Config: Only reads ~/.aws/config and ~/.aws/credentials - never writes
• ✅ Log Safety: Sensitive data (tokens, secrets) automatically masked in logs
• ✅ Environment Isolation: Supports AWS_CONFIG_FILE and AWS_SHARED_CREDENTIALS_FILE for custom config locations
• ✅ No Network Calls: All AWS operations delegated to official AWS CLI
• ✅ Subprocess Safety: Secure subprocess execution with proper escaping

Target metrics:

• Startup time: ≤ 300ms (cold start)
• Search response: ≤ 50ms (keystroke to UI update)
• Profile switch: ≤ 5s (including SSO login if needed)

Contributions are welcome! Please feel free to submit issues, feature requests, or pull requests.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass (uv run pytest)
6. Commit your changes (git commit -m 'Add amazing feature')
7. Push to the branch (git push origin feature/amazing-feature)
8. Open a Pull Request

See Development section above.

This project is licensed under the MIT License - see the LICENSE file for details.

• Textual - Modern TUI framework for Python
• uv - Fast Python package installer and resolver
• AWS CLI - Official AWS command-line tool
• Amazon Q Developer - AI-powered assistant for AWS

• AWS CLI SSO Configuration
• AWS CLI Assume Role
• Textual Documentation
• Amazon Q Developer CLI
• Python 3.13 Documentation

awsui - Making AWS Profile switching delightful! 🚀

If you find this tool useful, please consider giving it a ⭐ on GitHub!

Report Bug • Request Feature • PyPI Package