orbit-tui 1.1.0

Terminal UI for AWS - navigate, observe, and manage AWS resources
orbit-tui-1.1.0 is not a library. 
█▀█ █▀█ █▄▄ █ ▀█▀
█▄█ █▀▄ █▄█ █  █

orbit - Terminal UI for AWS

orbit 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.

License Rust

orbit is maintained independently. See Acknowledgments.

Screenshots

Features

  • Multi-Profile Support - Easily switch between AWS profiles
  • Multi-Region Support - Navigate across different AWS regions
  • 61 Resource Types - Browse and manage resources across 32 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

The crate is named orbit-tui (the name orbit was already taken on crates.io) but the binary it installs is orbit.

Using Cargo

cargo install --git https://github.com/doughlass/orbit

From Source

orbit is built with Rust. Make sure you have Rust 1.94+ 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/doughlass/orbit.git
cd orbit

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

Using Docker

# Build locally
docker build -t orbit .

# Run interactively
docker run --rm -it -v ~/.aws:/root/.aws:ro orbit

# Launch with a specific profile
docker run --rm -it -v ~/.aws:/root/.aws:ro orbit --profile production

# Launch in a specific region
docker run --rm -it -v ~/.aws:/root/.aws:ro orbit --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 \
  orbit

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

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

orbit 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

orbit supports AWS SSO. If your profile uses SSO and the token is expired, orbit 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, orbit will use the cached token automatically.

AWS Console Login

orbit supports AWS Console Login (aws login). If your profile uses login_session and credentials are expired, orbit 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, orbit will use the cached credentials automatically.

IAM Role Assumption

orbit 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: orbit-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 orbit with default profile
orbit

# Launch with a specific profile
orbit --profile production

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

# Enable debug logging
orbit --log-level debug

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

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

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

Log File Locations

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

Shell Completion

orbit supports shell completion for bash, zsh, fish, and PowerShell.

# Bash (add to ~/.bashrc)
eval "$(orbit completion bash)"

# Zsh (add to ~/.zshrc)
eval "$(orbit completion zsh)"

# Fish (add to ~/.config/fish/config.fish)
orbit completion fish | source

# PowerShell (add to $PROFILE)
orbit completion powershell | Out-String | Invoke-Expression

After adding the completion script, restart your shell or source the config file.

Key Bindings

Action Key Description
Navigation
Move up k / ↑ Move selection up
Move down j / ↓ Move selection down
Top gg / Home Jump to first item
Bottom G / End Jump to last item
Page up PgUp / Ctrl+b Scroll up one page
Page down PgDn / Ctrl+f Scroll down one page
Pagination
Next page ] Load next page of results
Previous page [ Load previous page of results
Views
Resource picker : Open resource type selector
Describe Enter / d View resource details
Back Esc / Backspace Go back to previous view
Help ? Show help screen
Actions
Refresh R Refresh current view (resets pagination)
Filter / Filter resources
Region shortcuts 0-5 Quick switch to common regions
Quit Ctrl-c Exit orbit
EC2 Actions
Connect (SSM) c Open SSM shell session to instance
Start instance s Start selected EC2 instance
Stop instance S Stop selected EC2 instance
Terminate Ctrl+d Terminate selected EC2 instance

Filtering

Press / to enter filter mode. orbit supports two types of filtering:

Local Filtering (All Resources)

Type any text to filter resources locally by name, ID, or other visible attributes. Uses fuzzy matching.

/web-server     # Filter by name containing "web-server"
/i-0123         # Filter by instance ID

AWS API Filtering (Server-Side)

For supported resources, you can filter using AWS API filters directly. This is more efficient for large resource lists as filtering happens server-side.

How to use:

  1. Press / to enter filter mode
  2. Type F and press Tab to autocomplete Filters:
  3. Enter filter key-value pairs: Filters: owner=amazon, architecture=arm64
  4. Press Enter to apply the filter (triggers AWS API call)
  5. Press Esc to clear the filter

Syntax:

Filters: key=value, key2=value2

Examples by Resource:

Resource Example Filters
AMIs Filters: owner=amazon, architecture=arm64, state=available
EC2 Instances Filters: instance-state-name=running, tag:Environment=prod
EBS Volumes Filters: status=available, tag:Name=my-volume
EBS Snapshots Filters: status=completed, owner-id=self

Common Filter Keys:

Filter Key Description Example Values
owner AMI owner (AMIs only) amazon, self, aws-marketplace, <account-id>
architecture CPU architecture arm64, x86_64
state / status Resource state available, running, stopped
tag:<key> Filter by tag tag:Environment=production

Note: When you enter filter mode on a supported resource, orbit shows available filter keys for that resource in the status bar.

Resource Navigation

Press : to open the resource picker. Type to filter resources:

:ec2          # EC2 Instances
:volumes      # EBS Volumes
:snapshots    # EBS Snapshots
:amis         # AMIs (Amazon Machine Images)
:lambda       # Lambda Functions
:s3           # S3 Buckets
:rds          # RDS Instances
:iam-users    # IAM Users
:eks          # EKS Clusters
:msk          # MSK Clusters

Use Tab to autocomplete and Enter to select.

Supported AWS Services

orbit supports 32 AWS services with 61 resource types covering 95%+ of typical AWS usage:

Category Service Resources
Compute EC2 Instances, Volumes, Snapshots, AMIs
Lambda Functions
ECS Clusters, Services, Tasks
EKS Clusters
Auto Scaling Auto Scaling Groups
Storage S3 Buckets, Objects
Database RDS Instances, Snapshots
DynamoDB Tables
ElastiCache Clusters
Redshift Clusters
Networking VPC VPCs, Subnets, Security Groups
ELBv2 Load Balancers, Listeners, Rules, Target Groups, Targets
Route 53 Hosted Zones
CloudFront Distributions
API Gateway REST APIs
Security IAM Users, Groups, Roles, Policies, Access Keys
Secrets Manager Secrets
KMS Keys
ACM Certificates
Cognito User Pools
Management CloudFormation Stacks
CloudWatch Log Groups
CloudTrail Trails
SSM Parameters
STS Caller Identity
Messaging SQS Queues
SNS Topics
EventBridge Event Buses, Rules
Containers ECR Repositories
DevOps CodePipeline Pipelines
CodeBuild Projects
Analytics Athena Workgroups
MSK Clusters

Missing a service? Open an issue to propose adding it!

Configuration

See Authentication for credential setup.

Environment Variables

Variable Description
AWS_PROFILE Default AWS profile to use
AWS_REGION Default AWS region
AWS_DEFAULT_REGION Fallback region (if AWS_REGION not set)
AWS_ACCESS_KEY_ID AWS access key
AWS_SECRET_ACCESS_KEY AWS secret key
AWS_SESSION_TOKEN AWS session token (for temporary credentials)
AWS_SHARED_CREDENTIALS_FILE Custom path to credentials file (default: ~/.aws/credentials)
AWS_CONFIG_FILE Custom path to config file (default: ~/.aws/config)
AWS_ENDPOINT_URL Custom endpoint URL (for LocalStack, etc.) - also used for STS AssumeRole
AWS_CA_BUNDLE Custom CA certificate bundle (PEM format) for corporate SSL inspection
SSL_CERT_FILE Alternative to AWS_CA_BUNDLE for custom CA certificates

Corporate Proxy / SSL Inspection

If you're behind a corporate proxy with SSL inspection, orbit may fail to connect to AWS services because the proxy's CA certificate is not trusted by default.

To fix this, set AWS_CA_BUNDLE or SSL_CERT_FILE to point to your corporate CA certificate bundle:

# Windows
set AWS_CA_BUNDLE=C:\path\to\corporate-ca-bundle.pem
orbit

# Linux/macOS
export AWS_CA_BUNDLE=/path/to/corporate-ca-bundle.pem
orbit

The PEM file can contain multiple certificates (certificate chain). orbit will load all certificates from the bundle and add them to the trusted root certificates.

Note: This is the same environment variable used by AWS CLI, so if AWS CLI works with your CA bundle, orbit should work too.

SSM Connect (EC2 Shell Access)

Press c on a running EC2 instance to open an interactive shell session via AWS Systems Manager.

Requirements:

  • session-manager-plugin must be installed
  • EC2 instance must have SSM Agent running
  • Instance must be running (not stopped/terminated)
  • Linux instances only (Windows not supported via shell)

Note: When you exit the shell session (exit), you'll return to orbit.

Known Issues

  • Some resources may require specific IAM permissions not covered by basic read-only policies
  • Total resource count is not displayed due to AWS API limitations (most AWS APIs don't return total count)
  • Some global services (IAM, Route53, CloudFront) always use us-east-1

Contributing

Contributions are welcome! Please see our Contributing Guide for details.

Important: Before adding a new AWS service, please open an issue first.

Acknowledgments

  • Inspired by k9s - the awesome Kubernetes CLI
  • Built with Ratatui - Rust TUI library
  • Uses aws-sigv4 for request signing

License

This project is licensed under the MIT License - see the LICENSE file for details. Copyright is retained by the original author, Hüseyin Babal, as required by the MIT licence.

orbit is an independent project. It is not affiliated with, endorsed by, or sponsored by Amazon Web Services, Inc. "AWS" is a trademark of Amazon.com, Inc. or its affiliates.