awsui

<p align="center"> <picture> <img src="images/logo.png" alt="awsui logo" width="400"> </picture> <br> </p> <p align="center"> <a href="https://pypi.org/project/awsui/"><img src="https://img.shields.io/pypi/v/awsui?color=blue" alt="PyPI version"></a> <a href="https://pypi.org/project/awsui/"><img src="https://img.shields.io/pypi/status/awsui" alt="PyPI status"></a> <a href="https://pypi.org/project/awsui/"><img src="https://img.shields.io/pypi/pyversions/awsui" alt="Python versions"></a> <a href="https://pypi.org/project/awsui/"><img src="https://img.shields.io/pypi/dw/awsui" alt="Downloads"></a> <br> <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a> <a href="https://textual.textualize.io/"><img src="https://img.shields.io/badge/TUI-Textual-cyan.svg" alt="Textual"></a> <a href="https://github.com/astral-sh/ruff"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json" alt="Ruff"></a> </p> <p align="center"> <a href="#"><img src="https://img.shields.io/badge/English-selected-blue" alt="English"></a> <a href="README_ZH_TW.md"><img src="https://img.shields.io/badge/繁體中文-available-lightgrey" alt="繁體中文"></a> </p> <h3 align="center"> A powerful, user-friendly terminal interface for AWS Profile and SSO management.<br> Built with <a href="https://textual.textualize.io/">Textual</a> for a modern, responsive TUI experience. </h3> <p align="center"> <strong>⚡ Fast</strong> • <strong>🔐 Secure</strong> • <strong>🤖 AI-Powered</strong> • <strong>🌍 Bilingual</strong> </p>

✨ 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

<p align="center"> <figure> <img src="images/demo01.png" alt="Profile search and switching" width="800"> <figcaption><i>⚡ Fast profile search and switching with real-time filtering</i></figcaption> </figure> </p> <p align="center"> <figure> <img src="images/demo02.png" alt="AWS CLI execution" width="800"> <figcaption><i>🎯 Smart CLI with command autocomplete and inline execution</i></figcaption> </figure> </p> <p align="center"> <figure> <img src="images/demo03.png" alt="Amazon Q AI assistant" width="800"> <figcaption><i>🤖 AI-powered Amazon Q Developer integration with streaming responses</i></figcaption> </figure> </p> <p align="center"> <figure> <img src="images/demo04.png" alt="AWS CLI cheatsheet" width="800"> <figcaption><i>📚 Built-in AWS CLI cheatsheet with quick reference for 15+ services</i></figcaption> </figure> </p>

📋 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

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
   

Usage

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