AWS Commander

A terminal-based user interface (TUI) for interacting with AWS services. AWS Commander provides an intuitive, keyboard-driven interface for browsing and managing AWS resources without leaving your terminal.

Features

• Interactive TUI: Navigate AWS resources using keyboard shortcuts
• Multiple AWS Service Support:
  • DynamoDB (tables, scan, query with support for GSI/LSI)
  • S3API (buckets, objects)
  • SQS (queues, messages)
  • And more...
• DynamoDB Query Builder: Interactive form-based query builder with automatic key detection
• Smart JSON Viewer:
  • Tree-based JSON visualization
  • Toggle between DynamoDB format and regular JSON (press 'n')
  • Support for nested JSON parsing
  • Base64 gzip decompression
• Reserved Word Handling: Automatic handling of DynamoDB reserved words in queries
• Pagination Support: Navigate through large result sets with next/previous page
• Profile Management: Switch between AWS profiles
• Search: Quick search across results (press ':')
• Copy to Clipboard: Copy data with 'y' key

Table of contents

1. Installation
2. What the Project Does
3. Key Bindings
4. Development
   1. Prerequisites
   2. Getting Started
   3. Running the Application
   4. Project Structure
   5. Build and Test
5. Versioning

Installation

Homebrew

brew tap cmd-tools/homebrew-tap
brew install aws-commander

From source

go install github.com/cmd-tools/aws-commander@latest

Manual download

Download the latest binary for your platform from the Releases page.

What the Project Does

AWS Commander is a terminal UI that wraps the AWS CLI, providing:

1. Easy AWS Resource Navigation: Browse services → resources → details without remembering CLI commands
2. DynamoDB Query Interface:
   • Automatically detects table keys (PK/SK) from table schema
   • Builds proper query expressions with expression attribute names/values
   • Handles DynamoDB reserved words (like STATUS, DATA, NAME, etc.)
   • Supports querying Global and Local Secondary Indexes
3. Smart JSON Inspection:
   • View DynamoDB items in both DynamoDB JSON format ({"S": "value"}) and regular JSON format
   • Toggle between formats with the 'n' key
   • Expand stringified JSON fields
   • Decompress base64-gzipped data
4. S3API Navigation: Browse buckets and objects
5. Result Caching: Fast navigation with intelligent result caching

Key Bindings

Key	Context	Description
ESC	Global	Go back / Navigate up
:	Global	Open search bar
n	Table view	Next page (pagination)
p	Table view	Previous page (pagination)
v	JSON viewer	Toggle DynamoDB/Normal JSON format
y	Any view	Copy (yank) current selection to clipboard
Ctrl+C	Any view	Copy current selection to clipboard
Enter	Table view	View item details or navigate into selection
Enter	JSON viewer	Expand stringified JSON or decompress gzip
?	Global	Show help

Development

Prerequisites

This project requires:

• Go 1.24.0 or later
• AWS CLI
• Docker (optional, for LocalStack)
• make (optional, for LocalStack)
  • Windows: MinGW or Cygwin
  • Linux: apt install make
  • Mac: brew install make

Getting Started

1. Clone the repository:

   git clone https://github.com/cmd-tools/aws-commander.git
   cd aws-commander

2. Install dependencies:

   go mod tidy

3. Build the application:

   go build -o aws-commander .

4. Run the application:

   ./aws-commander

   Or run directly with Go:

   go run .

5. Enable logging (optional):

   • Add --logview flag to show logs in the application
   • Or tail the log file: tail -f $TMPDIR/aws-commander.log (macOS/Linux)

Running the Application

With LocalStack (Development)

When using LocalStack, AWS Commander automatically uses the localstack profile configured in the project.

# Start LocalStack
make up

# Run AWS Commander
./aws-commander

# Stop LocalStack
make down

With Real AWS Account

Ensure you have AWS CLI configured with valid credentials:

# Configure AWS CLI (if not already done)
aws configure

# Run AWS Commander
./aws-commander

The application will prompt you to select an AWS profile from your ~/.aws/credentials file.

Navigation Flow Example

1. Start the application
2. Select a profile (e.g., localstack, default, or your custom profile)
3. Select a service (e.g., dynamodb, s3api, sqs)
4. Select a resource (e.g., table name, bucket name)
5. Select an action (e.g., scan, query, list-objects)
6. View results in table format
7. Press Enter on a row to view JSON details
8. Press v in JSON view to toggle between DynamoDB and regular JSON format
9. Press ESC to go back
10. Press : to search within results

Project Structure

Package	Purpose
main (root)	Entry point, handlers, views, navigation, search
cmd/	Domain types, config loading, UI state
cmd/profile/	AWS profile discovery and SSO handling
parser/	Command output parsing and content view creation
ui/	Reusable TUI components (table, list, tree, modal, toast)
executor/	Shell command execution wrapper
logger/	Logging singleton
constants/	Shared string constants
helpers/	String utilities, AWS version detection
configurations/	YAML service definitions for AWS commands

Build and Test

# Build
go build ./...

# Run all tests
go test ./...

# Run tests with race detector
go test -race ./...

# Run a specific test
go test ./parser/ -run Test_ParseCommand_Object

# Static analysis
go vet ./...

# Format check
gofmt -l .

Versioning

We use SemVer for versioning.