<p align="center"> <img src="assets/taws-logo.png" alt="taws" width="400"/> </p>

taws - Terminal UI for AWS

taws provides a terminal UI to interact with your AWS resources. The aim of this project is to make it easier to navigate, observe, and manage your AWS infrastructure in the wild.

---

---

Screenshots

<p align="center"> <img src="assets/screenshot-ec2.png" alt="EC2 Instances View" width="800"/> </p> <p align="center"> <img src="assets/screenshot-lambda.png" alt="Lambda Functions View" width="800"/> </p>

---

Features

• Multi-Profile Support - Easily switch between AWS profiles
• Multi-Region Support - Navigate across different AWS regions
• 94+ Resource Types - Browse and manage resources across 60+ AWS services
• Manual Refresh - Refresh resources with a single keystroke
• Pagination - Navigate through large resource lists with ] / [ keys
• Keyboard-Driven - Vim-like navigation and commands
• Resource Actions - Start, stop, terminate EC2 instances directly
• Detailed Views - JSON/YAML view of resource details
• Filtering - Filter resources locally with fuzzy matching, or by AWS tags (server-side) for supported resources
• Autocomplete - Smart resource type autocomplete with fuzzy matching

---

Installation

Homebrew (macOS/Linux)

brew install huseyinbabal/tap/taws

Scoop (Windows)

scoop bucket add huseyinbabal https://github.com/huseyinbabal/scoop-bucket
scoop install taws

Download Pre-built Binaries

Download the latest release from the Releases page.

| Platform | Architecture | Download | |----------|--------------|----------| | macOS | Apple Silicon (M1/M2/M3) | taws-aarch64-apple-darwin.tar.gz | | macOS | Intel | taws-x86_64-apple-darwin.tar.gz | | Linux | x86_64 (musl) | taws-x86_64-unknown-linux-musl.tar.gz | | Linux | ARM64 (musl) | taws-aarch64-unknown-linux-musl.tar.gz | | Windows | x86_64 | taws-x86_64-pc-windows-msvc.zip |

Quick Install (macOS/Linux)

# macOS Apple Silicon
curl -sL https://github.com/huseyinbabal/taws/releases/latest/download/taws-aarch64-apple-darwin.tar.gz | tar xz
sudo mv taws /usr/local/bin/

# macOS Intel
curl -sL https://github.com/huseyinbabal/taws/releases/latest/download/taws-x86_64-apple-darwin.tar.gz | tar xz
sudo mv taws /usr/local/bin/

# Linux x86_64 (musl - works on Alpine, Void, etc.)
curl -sL https://github.com/huseyinbabal/taws/releases/latest/download/taws-x86_64-unknown-linux-musl.tar.gz | tar xz
sudo mv taws /usr/local/bin/

# Linux ARM64 (musl - works on Alpine, Void, etc.)
curl -sL https://github.com/huseyinbabal/taws/releases/latest/download/taws-aarch64-unknown-linux-musl.tar.gz | tar xz
sudo mv taws /usr/local/bin/

Windows

1. Download taws-x86_64-pc-windows-msvc.zip from the Releases page
2. Extract the zip file
3. Add the extracted folder to your PATH, or move taws.exe to a directory in your PATH

Using Cargo

cargo install taws

Using Docker

# Run interactively
docker run --rm -it ghcr.io/huseyinbabal/taws

# Launch with a specific profile (mount AWS credentials)
docker run --rm -it \
  -v ~/.aws:/root/.aws:ro \
  ghcr.io/huseyinbabal/taws --profile production

# Launch in a specific region
docker run --rm -it \
  -v ~/.aws:/root/.aws:ro \
  ghcr.io/huseyinbabal/taws --region us-west-2

# Using environment variables
docker run --rm -it \
  -e AWS_ACCESS_KEY_ID=$AWS_ACCESS_KEY_ID \
  -e AWS_SECRET_ACCESS_KEY=$AWS_SECRET_ACCESS_KEY \
  -e AWS_REGION=us-east-1 \
  ghcr.io/huseyinbabal/taws

# Build locally
docker build -t taws .
docker run --rm -it -v ~/.aws:/root/.aws:ro taws

Note: Use -it flags for interactive terminal support (required for TUI). Mount your ~/.aws directory as read-only to use your existing AWS credentials.

From Source

taws is built with Rust. Make sure you have Rust 1.70+ installed, along with a C compiler and linker.

Build Dependencies

| Platform | Install Command | |----------|-----------------| | Amazon Linux / RHEL / Fedora | sudo yum groupinstall "Development Tools" -y | | Ubuntu / Debian | sudo apt update && sudo apt install build-essential -y | | macOS | xcode-select --install | | Windows | Install Visual Studio Build Tools |

# Clone the repository
git clone https://github.com/huseyinbabal/taws.git
cd taws

# Build and run
cargo build --release
./target/release/taws

---

Prerequisites

• AWS Credentials - See Authentication section below
• IAM Permissions - Your AWS user/role needs appropriate read permissions for the services you want to browse. At minimum, you'll need Describe* and List* permissions.

---

Authentication

taws uses a credential chain, trying each source in order:

| Priority | Source | Description | |----------|--------|-------------| | 1 | Environment Variables | AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN | | 2 | AWS SSO | If profile has SSO configured, uses SSO (prompts for login if needed) | | 3 | AWS Console Login | If profile has login_session configured, prompts for console login | | 4 | Role Assumption | If profile has role_arn + source_profile, assumes the role | | 5 | Credentials File | ~/.aws/credentials | | 6 | Config File | ~/.aws/config | | 7 | IMDSv2 | EC2 instance metadata |

AWS SSO

taws supports AWS SSO. If your profile uses SSO and the token is expired, taws will prompt you to authenticate via browser.

Both SSO config formats are supported:

• Modern: sso_session reference to [sso-session X] section
• Legacy: sso_start_url directly in profile

If you already logged in via aws sso login, taws will use the cached token automatically.

AWS Console Login

taws supports AWS Console Login (aws login). If your profile uses login_session and credentials are expired, taws will prompt you to run aws login in another terminal.

[profile console-profile]
login_session = my-login-session

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

If you already logged in via aws login, taws will use the cached credentials automatically.

IAM Role Assumption

taws supports assuming IAM roles using role_arn with either source_profile or credential_source. This is commonly used for:

• Cross-account access (e.g., dev account assuming role in prod account)
• Least-privilege access patterns
• Chained role assumption
• Container-based deployments (ECS, Lambda)

Using source_profile

Reference another named profile for source credentials:

[profile base]
region = us-east-1

[profile production]
role_arn = arn:aws:iam::123456789012:role/ProductionAccess
source_profile = base
region = us-west-2

# Optional: external_id for cross-account trust
[profile partner-account]
role_arn = arn:aws:iam::987654321098:role/PartnerAccess
source_profile = base
external_id = my-external-id

Using credential_source

Load source credentials from environment, EC2 metadata, or ECS container:

# For ECS tasks with task IAM roles
[profile ecs-admin]
role_arn = arn:aws:iam::123456789012:role/AdminRole
credential_source = EcsContainer

# For EC2 instances with instance roles
[profile ec2-admin]
role_arn = arn:aws:iam::123456789012:role/AdminRole
credential_source = Ec2InstanceMetadata

# For environments with AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY set
[profile env-admin]
role_arn = arn:aws:iam::123456789012:role/AdminRole
credential_source = Environment

Supported credential_source values:

| Value | Description | |-------|-------------| | Environment | Load from AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN | | Ec2InstanceMetadata | Load from EC2 instance metadata (IMDSv2) | | EcsContainer | Load from ECS container credentials endpoint |

Supported options:

| Option | Required | Description | |--------|----------|-------------| | role_arn | Yes | ARN of the IAM role to assume | | source_profile | One of | Profile to use for source credentials | | credential_source | these | Where to load source credentials from | | external_id | No | External ID for cross-account trust policies | | role_session_name | No | Custom session name (default: taws-session) | | duration_seconds | No | Session duration in seconds (default: 3600) | | region | No | Region for STS endpoint |

Notes:

• Use exactly one of source_profile OR credential_source (not both)
• Chained role assumption is supported (source_profile can also use role_arn)
• Temporary credentials are cached and automatically refreshed before expiration
• ECS container credentials require AWS_CONTAINER_CREDENTIALS_RELATIVE_URI or AWS_CONTAINER_CREDENTIALS_FULL_URI environment variables (set automatically by ECS)

---

Quick Start

# Launch taws with default profile
taws

# Launch with a specific profile
taws --profile production

# Launch in a specific region
taws --region us-west-2

# Enable debug logging
taws --log-level debug

# Run in read-only mode (blocks all write operations)
taws --readonly

# Use with LocalStack or custom endpoint
taws --endpoint-url http://localhost:4566

# Or via environment variable
AWS_ENDPOINT_URL=http://localhost:4566 taws

Log File Locations

| Platform | Path | |----------|------| | Linux | ~/.config/taws/taws.log | | macOS | ~/Library/Application Support/taws/taws.log | | Windows | %APPDATA%\taws\taws.log |