awsui

A powerful, user-friendly terminal interface for AWS Profile and SSO management.
Built with Textual for a modern, responsive TUI experience.

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

✨ Why awsui?

⚡ 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

🎬 Demo

⚡ Fast profile search and switching with real-time filtering

🎯 Smart CLI with command autocomplete and inline execution

🤖 AI-powered Amazon Q Developer integration with streaming responses

📚 Built-in AWS CLI cheatsheet with quick reference for 15+ services

📋 Features

Core Features

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

AI Assistant

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

CLI Features

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

Developer Experience

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

⚡ Quick Start

# 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. 🚀

📦 Requirements

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)

🚀 Installation

Option 1: Install with uv (Recommended)

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

# Run directly
awsui

Option 2: Install with pip

pip install awsui

# Run
awsui

Option 3: Development Setup

# 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

📖 Usage

Interactive Mode

Launch the TUI to select and switch profiles:

awsui

Keyboard Shortcuts:

Category	Key	Action
🔍 Navigation	`/`	Focus search box
	`↑` `↓`	Navigate profiles
	`Enter`	Apply selected profile
	`Esc`	Leave input field
💻 CLI & Tools	`c`	Focus CLI input
	`a`	Toggle AI assistant panel
	`h`	Show AWS CLI cheatsheet
	`t`	Toggle left pane (profile list)
🔐 AWS	`l`	Force SSO login for selected profile
	`w`	Show current AWS identity (WhoAmI)
⚙️ System	`Ctrl+L`	Clear CLI output
	`Ctrl+U`	Clear CLI input
	`?`	Show help
	`q`	Quit

Pre-select Profile

Skip interactive selection:

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

Override Region

Temporarily override AWS region:

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

Language Selection

# English (default)
awsui --lang en

# Traditional Chinese
awsui --lang zh-TW

Debug Mode

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

🤖 AI Assistant (Amazon Q Developer)

Setup

Install Amazon Q Developer CLI:

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

Verify installation:
```
q --version
```

Usage

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

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

⚙️ AWS Configuration

SSO Session Configuration

~/.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

Assume Role Configuration

[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

Legacy SSO (without sso-session)

[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

📁 Project Structure

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

🧪 Development

Run Tests

uv run pytest

Test Coverage

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

Install Dev Dependencies

uv sync --dev

Code Quality

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

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

🐛 Troubleshooting

AWS CLI Not Found - E_NO_AWS: AWS CLI v2 not detected

Solution: Install AWS CLI v2 following the official guide

Verify installation:

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

No Profiles Available - E_NO_PROFILES: No profiles detected

Solution: Configure at least one profile:

# For SSO
aws configure sso-session

# For legacy SSO
aws configure sso

# For static credentials
aws configure

SSO Login Fails - E_LOGIN_FAIL: SSO login failed

Possible causes:

Network connectivity issues
Invalid SSO start URL
MFA/2FA not completed
Browser not opening (check firewall/permissions)

Solution:

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

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

Identity Check Fails - E_STS_FAIL: Unable to fetch identity

Possible causes:

Credentials expired (SSO token or assume-role session)
Invalid profile configuration
Network/VPC issues
Missing IAM permissions

Solution:

# 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

Amazon Q Not Available - Amazon Q CLI not available

Solution: Install Amazon Q Developer CLI:

# macOS
brew install amazon-q

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

Verify installation:

q --version

🔒 Security

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

🎯 Performance

Target metrics:

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

🤝 Contributing

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

Guidelines

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

Development Setup

See Development section above.

📄 License

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

🙏 Acknowledgments

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

📚 References

✨ Made with ❤️ for AWS Developers ✨

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

Name		Name	Last commit message	Last commit date
Latest commit History 21 Commits
.github/workflows		.github/workflows
awsui		awsui
docs		docs
images		images
tests		tests
.gitignore		.gitignore
.python-version		.python-version
LICENSE		LICENSE
README.md		README.md
README_ZH_TW.md		README_ZH_TW.md
pyproject.toml		pyproject.toml
uv.lock		uv.lock

Folders and files

Latest commit

History

Repository files navigation