awx — AWS Developer Toolkit for the Terminal

Production-grade CLI for Lambda, SQS, DynamoDB, EventBridge, SSM, and Secrets Manager. Built for developers who live in the terminal.

Table of Contents

• Why awx?
• Supported Services
• Prerequisites
• Installation
• Quick Start
• Commands
  • 🔐 Authentication
    • Cross-Account Role Switching
  • ⚡ Lambda
  • 📨 SQS
  • 🗄️ DynamoDB
  • 🔀 EventBridge
  • ⚙️ SSM Parameter Store
  • 🔴 API Gateway
  • 🟠 CloudFormation
  • 🟢 S3
  • 🔑 Secrets Manager
  • 📊 Observability
• Global Flags
• Output Formats
• Environment Variables
• Real-World Workflows
• Configuration
• Troubleshooting
• Tech Stack
• Contributing
• License

Why awx?

The AWS Console is great for exploration but painful for daily operations. The official AWS CLI is powerful but verbose — every command requires knowing the exact API shape, and the output is raw JSON that's hard to read at a glance.

awx is designed around the workflows developers actually do:

• Tail logs while debugging a production issue
• Invoke a function with a test payload and see the result immediately
• Inspect a dead letter queue, understand why messages failed, and replay them
• Switch between accounts as easily as changing a Git branch

It behaves like tools you already know — kubectl, gh, the Heroku CLI — but for AWS.

# What the AWS CLI requires
aws logs filter-log-events \
  --log-group-name /aws/lambda/order-processor \
  --start-time $(date -d '1 hour ago' +%s000) \
  --filter-pattern ERROR \
  --query 'events[*].message' \
  --output text

# What awx requires
awx lambda logs tail order-processor --last 1h --filter ERROR

Supported Services

| Icon | Service | Key Commands | | ---- | ----------------------- | ----------------------------------------------------------------------- | | 🔐 | Authentication | login · switch · assume · status · logout · roles | | ⚡ | Lambda | list · info · invoke · logs · metrics · benchmark | | 📨 | SQS | list · receive · send · dlq · purge · move · monitor | | 🗄️ | DynamoDB | list · info · get · query · scan · put · delete | | 🔀 | EventBridge | list · rules · targets · send · enable · disable | | ⚙️ | SSM Parameter Store | list · get · put · delete · history | | 🔑 | Secrets Manager | list · get · create · update · delete · rotate · versions | | 🔴 | API Gateway | list · info · stages · resources · keys | | 🟠 | CloudFormation | list · info · resources · events · outputs · drift | | 🟢 | S3 | list · info · ls · get · put · delete · presign | | 📊 | Observability | errors · trace · oncall · watch · dashboard |

Prerequisites

| Requirement | Version | Notes | | --------------- | ----------------- | -------------------------------------- | | Node.js | >= 20.0.0 | Check with node --version | | npm | >= 8.0.0 | Comes with Node | | AWS credentials | Any method | See Authentication | | AWS CLI | >= 2.x (optional) | Required only for SSO login |

Installation

# From npm (recommended)
npm install -g awx-cli

# Verify
awx --version
awx --help

git clone https://github.com/your-org/aws-cli-commands
cd aws-cli-commands
npm install
npm run build
npm link

Quick Start

# Step 1 — Authenticate
awx auth login

# Step 2 — Verify your session
awx auth status

# Step 3 — Explore your AWS resources
awx lambda list                              # Lambda functions
awx sqs list                                 # SQS queues
awx dynamo list                              # DynamoDB tables
awx dynamo query orders --pk user#123        # Query a table
awx eb list                                  # EventBridge buses
awx ssm list /myapp/prod                     # SSM parameters by path
awx ssm get /myapp/prod/db-pass --decrypt    # Decrypt a SecureString
awx secrets list                             # Secrets Manager secrets
awx secrets get my-api-key                   # Reveal a secret value
awx apigw list                               # API Gateway REST APIs
awx apigw stages my-api                      # Stages with invoke URLs
awx cfn list                                 # CloudFormation stacks
awx cfn outputs my-stack                     # Stack outputs
awx s3 list                                  # S3 buckets
awx s3 ls my-bucket images/                  # List objects in a path

Commands

🔐 Authentication

# Login — interactive wizard (SSO / profile / access keys + MFA / access keys)
awx auth login

# Check current session (account, region, identity, expiry)
awx auth status

# Switch between profiles
awx auth switch                          # interactive picker
awx auth switch production               # direct switch

# Assume an IAM role
awx auth assume arn:aws:iam::123456789012:role/PlatformEngineer
awx auth assume arn:aws:iam::123456789012:role/Admin --mfa

# Logout
awx auth logout
awx auth logout --force                  # skip confirmation

Access Keys + MFA flow — for teams that log into the AWS Console with an account ID, IAM username, and an MFA device:

awx auth login
? How does your team access AWS? → Access Keys + MFA

? Profile name to save as:  default
? Access Key ID:             AKIA...
? Secret Access Key:         ****
? Default region:            eu-west-1
? MFA device ARN:            arn:aws:iam::123456789012:mfa/john.doe
? MFA token code:            847291

✔ Authenticated as arn:aws:iam::123456789012:user/john.doe
  Account      123456789012
  Region       eu-west-1
  Session      valid until 10:45 PM on Thu, Jun 11

The session token is valid for 12 hours. When it expires, run awx auth login again and enter a fresh MFA code — same flow, one command.

Login methods:

| Method | When to use | | ----------------- | ------------------------------------------------------------ | | AWS SSO | Teams using Okta, Azure AD, or AWS Identity Center | | Named Profile | Already have ~/.aws/credentials configured | | Access Keys + MFA | IAM user with MFA enforced — the standard Console login flow | | Access Keys | CI/CD or env-var based credentials without MFA |

Cross-Account Role Switching

awx auth roles manages cross-account IAM roles — save shortcuts, list all configured roles, and switch between accounts with a single command.

# List all cross-account roles (from ~/.aws/config and awx config)
awx auth roles list

# Save a role shortcut
awx auth roles add prod-admin \
  --arn arn:aws:iam::123456789012:role/AdminRole \
  --region eu-west-1

# Save with MFA requirement
awx auth roles add prod-admin \
  --arn arn:aws:iam::123456789012:role/AdminRole \
  --region eu-west-1 \
  --mfa-serial arn:aws:iam::987654321098:mfa/john.doe

# Save and verify the role can be assumed immediately
awx auth roles add prod-admin --arn <arn> --region eu-west-1 --test

# Switch to a cross-account role
awx auth roles switch prod-admin         # direct switch
awx auth roles switch                    # interactive picker

# Show which role/account is currently active
awx auth roles current

# Remove a saved role shortcut
awx auth roles remove prod-admin

Note: Profiles in ~/.aws/config that have a role_arn field are automatically discovered by awx auth roles list and awx auth roles switch — no re-registration needed. Roles saved via awx auth roles add also appear in awx auth switch.

⚡ Lambda

List & Inspect

awx lambda list                          # list all functions
awx lambda list --all                    # skip 20-item default cap
awx lambda list --runtime node20.x       # filter by runtime

awx lambda info order-processor          # full function detail
awx lambda info order-processor --show-env   # include env vars

Functions using deprecated runtimes (Node 16, Python 3.6) are flagged with ⚠.

Invoke

awx lambda invoke                        # interactive — opens payload editor
awx lambda invoke order-processor --payload '{"orderId": "ORD-123"}'
awx lambda invoke order-processor --payload-file ./payload.json --logs
awx lambda invoke order-processor --payload-file event.json --async
awx lambda invoke order-processor --qualifier production

⚠ invoke executes your function for real. Charges, emails, and DB writes are real. See AWS Costs.

Logs

# Tail recent logs
awx lambda logs tail order-processor                         # last 15m
awx lambda logs tail order-processor --last 1h --filter ERROR

# Stream continuously
awx lambda logs follow order-processor --filter ERROR

# Search by pattern or request ID
awx lambda logs search order-processor --filter '"Payment timeout"' --last 6h
awx lambda logs search order-processor --request-id abc-123-def-456

--last time formats: 15m · 1h · 6h · 2d · 1w · 2026-01-15T10:00:00

Configuration

awx lambda config get order-processor
awx lambda config set order-processor --timeout 30 --memory 512
awx lambda config env:set order-processor --key LOG_LEVEL --value debug
awx lambda config env:unset order-processor --key OLD_KEY

Versions, Aliases & Triggers

awx lambda versions order-processor     # published versions
awx lambda aliases order-processor      # aliases with traffic weights
awx lambda triggers order-processor     # event sources + EventBridge rules
awx lambda layers list --runtime node20.x
awx lambda permissions order-processor  # resource-based policy

Metrics & Benchmark

# CloudWatch metrics — p50/p95/p99 duration, error rate, throttles
awx lambda metrics order-processor
awx lambda metrics order-processor --last 1h

# Benchmark — invoke N times, show latency distribution
awx lambda benchmark order-processor --runs 20 --concurrency 5
awx lambda benchmark order-processor --payload-file payload.json --runs 10

📨 SQS

# List queues
awx sqs list                             # all queues
awx sqs list --dlq                       # only DLQs
awx sqs list --fifo                      # only FIFO queues

# Queue detail
awx sqs info order-events-queue

# Receive messages
awx sqs receive order-events-queue --max 3
awx sqs receive order-events-queue --follow     # continuous poll

# Send a message
awx sqs send order-events-queue --message '{"orderId": "ORD-456"}'
awx sqs send order-events-queue --file ./event.json --delay 30

# Dead letter queue workflow
awx sqs dlq inspect failed-orders-dlq
awx sqs dlq replay failed-orders-dlq --to order-events-queue --dry-run
awx sqs dlq replay failed-orders-dlq --to order-events-queue
awx sqs dlq drain failed-orders-dlq --force

# Purge (AWS native — 60s cooldown between calls)
awx sqs purge order-events-queue --force

# Move messages between queues
awx sqs move order-events-queue --to order-archive-queue --dry-run
awx sqs move order-events-queue --to order-archive-queue --max 50

# Live monitor — depth, in-flight, trend arrows, refreshes every 5s
awx sqs monitor order-events-queue
awx sqs monitor order-events-queue --interval 10

⚠ drain and purge permanently delete all messages — irreversible.

🗄️ DynamoDB

# List tables
awx dynamo list

# Table detail — key schema, GSIs/LSIs, billing mode
awx dynamo info orders

# Get item by primary key
awx dynamo get orders --pk "user#123" --sk "order#456"

# Query by partition key (with optional SK conditions)
awx dynamo query orders --pk user#123
awx dynamo query orders --pk user#123 --sk-begins "order#2024"
awx dynamo query orders --pk user#123 --sk-between "order#2024-01" "order#2024-12"

# Scan (use with caution on large tables)
awx dynamo scan orders --limit 100
awx dynamo scan orders --filter '{"status": "pending"}'

# Write / delete items
awx dynamo put orders --item '{"userId": "user#123", "orderId": "order#001"}'
awx dynamo put orders --file ./item.json
awx dynamo delete orders --pk "user#123" --sk "order#456"

# Indexes — list all GSIs and LSIs
awx dynamo indexes orders

🔀 EventBridge

# Buses
awx eb list

# Rules — list, inspect, enable/disable
awx eb rules list                        # rules on default bus
awx eb rules list --bus my-custom-bus
awx eb rules list --state disabled       # filter by state
awx eb rules info my-rule                # detail + targets
awx eb rules enable my-rule
awx eb rules disable my-rule

# Targets
awx eb targets my-rule

# Send a test event
awx eb send \
  --source my-app \
  --detail-type OrderPlaced \
  --detail '{"orderId": "ORD-789"}'

awx lambda triggers shows EventBridge rules alongside event source mappings. awx oncall surfaces any unexpectedly disabled rules.

⚙️ SSM Parameter Store

# List parameters
awx ssm list                             # all parameters
awx ssm list /myapp/prod                 # filter by path prefix
awx ssm list /myapp --no-recursive       # top-level only

# Get a parameter value
awx ssm get /myapp/prod/db-host
awx ssm get /myapp/prod/db-pass --decrypt    # required for SecureString

# Create or update
awx ssm put /myapp/prod/feature-flag --value "true"
awx ssm put /myapp/prod/db-pass --value "s3cr3t" --type SecureString --overwrite
awx ssm put /myapp/prod/db-pass --value "s3cr3t" --type SecureString --key-id alias/mykey

# Delete
awx ssm delete /myapp/prod/old-key
awx ssm rm /myapp/prod/old-key           # alias

# Version history
awx ssm history /myapp/prod/db-pass

Parameter types: String · StringList · SecureString

🔴 API Gateway

# List REST APIs
awx apigw list

# Full API detail + all stages with invoke URLs
awx apigw info my-api

# Stages with invoke URLs and cache status
awx apigw stages my-api

# Resource path tree with colour-coded HTTP methods
awx apigw resources my-api

# API keys (values never shown)
awx apigw keys

🟠 CloudFormation

# List stacks — colour-coded status, drift badge
awx cfn list
awx cfn list --all                              # include DELETE_COMPLETE

# Full stack detail — parameters, outputs, capabilities
awx cfn info my-stack

# All resources with type, status, drift
awx cfn resources my-stack

# Deployment events (newest first, failure reasons inline)
awx cfn events my-stack
awx cfn events my-stack --limit 100

# Just the outputs (ARNs, URLs, resource names)
awx cfn outputs my-stack

# Drift detection
awx cfn drift my-stack                          # last known status (instant)
awx cfn drift my-stack --detect                 # run fresh detection (30–90s)

🟢 S3

# List all buckets
awx s3 list

# Bucket detail — region, versioning, encryption, public access
awx s3 info my-bucket

# List objects (folder-style by default)
awx s3 ls my-bucket
awx s3 ls my-bucket images/                     # specific prefix
awx s3 ls my-bucket --all                       # recursive

# Download / upload / delete
awx s3 get my-bucket report.pdf
awx s3 put my-bucket report.pdf --file ./report.pdf
awx s3 delete my-bucket old-file.json --yes

# Presigned URL (temporary unauthenticated access)
awx s3 presign my-bucket report.pdf             # 1 hour default
awx s3 presign my-bucket report.pdf --expires 86400

🔑 Secrets Manager

# List secrets — shows rotation status, last changed date
awx secrets list

# Get a secret value (auto-pretty-prints JSON)
awx secrets get my-api-key
awx secrets get my-db-credentials --raw       # skip JSON formatting
awx secrets get my-db-credentials --info      # include metadata

# Create / update
awx secrets create my-api-key --value "sk-abc123" --description "Stripe API key"
awx secrets create my-db-creds --value-file ./creds.json
awx secrets update my-api-key --value "sk-xyz456"

# Delete
awx secrets delete my-old-key                 # 30-day recovery window (default)
awx secrets delete my-old-key --recovery-days 7
awx secrets delete my-old-key --force         # immediate permanent deletion

# Rotation
awx secrets rotate my-db-credentials          # triggers configured rotation Lambda

# Version history
awx secrets versions my-db-credentials        # AWSCURRENT highlighted in green

⚠ Secrets Manager is billed at $0.40/secret/month with no free tier. --force delete is immediate and unrecoverable.

📊 Observability

awx errors — Error rates across all functions

awx errors                               # last 15 minutes
awx errors --last 1h
awx errors --last 6h --all               # include healthy functions
awx errors --min-errors 5

awx trace — Cross-service request correlation

awx trace abc-123-def-456                # search all Lambda log groups
awx trace abc-123-def-456 --last 6h
awx trace abc-123-def-456 --prefix /aws/lambda/payment-

awx oncall — Production health report

awx oncall                               # last 8 hours
awx oncall --last 24h

Output: Lambda error rates · DLQs with depth · queues above 1,000 messages · disabled EventBridge rules.

awx watch — Threshold alarms

awx watch \
  --alarm "error-rate:payment-handler > 5" \
  --alarm "dlq-depth:failed-orders-dlq > 100" \
  --alarm "queue-depth:order-events-queue > 10000" \
  --alarm "rule-state:order-fanout-rule"

Alarm types:

| Type | Format | Example | | ----------------- | --------------------------- | ----------------------------------- | | Lambda error rate | error-rate:<fn> > <pct> | error-rate:payment-handler > 5 | | DLQ depth | dlq-depth:<queue> > <n> | dlq-depth:failed-orders-dlq > 100 | | Queue depth | queue-depth:<queue> > <n> | queue-depth:order-queue > 10000 | | EventBridge rule | rule-state:<rule>[@<bus>] | rule-state:order-fanout-rule |

awx dashboard — Full-screen live TUI

awx dashboard
awx dashboard --interval 5 --last 1h

| Key | Action | | ----------- | ------------- | | q / Esc | Quit | | r | Force refresh | | Tab | Switch panels | | ↑ / ↓ | Navigate rows |

Global Flags

Available on every command:

| Flag | Description | Default | | ------------------- | ------------------------------------- | ------------------ | | --profile <name> | AWS profile to use | awx config default | | --region <region> | AWS region override | awx config default | | --output <format> | human | json | table | tsv | human | | --no-color | Disable all colours | — | | --quiet | Suppress spinners and progress | — | | --debug | Show raw AWS API calls | — | | -v, --version | Print awx version | — | | -h, --help | Help for any command | — |

# Cross-account without switching profile
awx lambda list --profile production --region us-east-1

# JSON output for piping
awx lambda list --output json | jq '.[].name'
awx sqs receive my-queue --output json | jq '.[0].body | fromjson'

# CI-friendly
awx sqs list --no-color --quiet --output json

Output Formats

| Format | Best for | | ------- | ----------------------------------- | | human | Interactive use — coloured, aligned | | json | Scripting and piping to jq | | table | Side-by-side comparisons | | tsv | Spreadsheets, awk, cut |

Environment Variables

AWX_PROFILE=production   # same as --profile
AWX_REGION=us-east-1     # same as --region
AWX_DEBUG=1              # same as --debug

# Standard AWS variables — all respected
AWS_PROFILE=staging
AWS_DEFAULT_REGION=eu-west-1
AWS_ACCESS_KEY_ID=...
AWS_SECRET_ACCESS_KEY=...
AWS_SESSION_TOKEN=...

Resolution priority: --profile flag → AWX_PROFILE → AWS_PROFILE → awx config → ~/.aws/config → SDK default

Real-World Workflows

awx lambda logs tail order-processor --last 1h --filter ERROR
awx lambda logs follow order-processor --filter ERROR
awx lambda invoke order-processor --payload-file ./test-event.json --logs
awx lambda logs search order-processor --request-id abc-123-def

awx sqs dlq inspect failed-orders-dlq
awx sqs dlq replay failed-orders-dlq --to order-events-queue --dry-run
awx sqs dlq replay failed-orders-dlq --to order-events-queue
awx sqs receive order-events-queue --follow

awx auth status
awx auth switch production
awx lambda list --region eu-west-1
awx lambda invoke payment-handler --payload-file prod-event.json
awx auth switch staging

# One-time setup — save role shortcuts
awx auth roles add dev-admin \
  --arn arn:aws:iam::111111111111:role/DeveloperRole \
  --region eu-west-1

awx auth roles add prod-readonly \
  --arn arn:aws:iam::222222222222:role/ReadOnlyRole \
  --region eu-west-1

# See all configured roles at a glance
awx auth roles list

# Switch to prod for inspection
awx auth roles switch prod-readonly
awx lambda list
awx cfn list

# Switch back to dev for deployment
awx auth roles switch dev-admin
awx lambda invoke order-processor --payload-file event.json

awx secrets list
awx secrets get my-db-credentials
awx secrets update my-db-credentials --value '{"username":"admin","password":"new-pass"}'
awx secrets rotate my-db-credentials
awx secrets versions my-db-credentials

awx ssm list /myapp/prod
awx ssm get /myapp/prod/db-password --decrypt
awx ssm put /myapp/prod/feature-flag --value "true" --overwrite
awx ssm history /myapp/prod/db-password

# Tab 1 — watch queue live
awx sqs receive order-events-queue --follow

# Tab 2 — send test messages
for i in {1..100}; do
  awx sqs send order-events-queue --message "{\"orderId\": \"ORD-$i\"}"
done

Configuration

awx stores config at:

| OS | Path | | ------- | --------------------------------------- | | macOS | ~/Library/Preferences/awx/config.json | | Linux | ~/.config/awx/config.json | | Windows | %APPDATA%\awx\config.json |

awx config get                           # show current config
awx config set defaultRegion eu-west-1
awx config set defaultProfile staging
awx config set defaultOutput json

Credentials are never stored here — only profile name references.

Shell Completion

awx completion install --shell zsh       # adds to ~/.zshrc
awx completion install --shell bash
awx completion install --shell fish

Troubleshooting

awx auth login

The error message shows the exact permission needed.

awx auth switch <profile-with-access>
awx auth assume arn:aws:iam::123456789012:role/PowerUser

awx auth status          # verify account + region
awx lambda list          # see what's actually there

awx also suggests the closest matching name on typos: Did you mean: order-processor ?

awx lambda list --debug
# or
AWX_DEBUG=1 awx lambda list

Tech Stack

| Package | Purpose | | ------------------- | -------------------------------- | | TypeScript 5 | Type safety throughout | | Commander.js | CLI command framework | | AWS SDK v3 | AWS API calls | | Chalk | Terminal colours | | Ora | Spinners and progress | | @inquirer/prompts | Interactive selectors | | Ink | React-based TUI components | | Zod | Config schema validation | | conf | Persistent cross-platform config | | fuse.js | Fuzzy search in selectors | | Vitest | Unit and integration testing | | tsup | Fast ESM build with esbuild |

Contributing

git clone https://github.com/your-org/aws-cli-commands
cd aws-cli-commands
npm install
npm run dev -- lambda list    # dev mode, no build step
npm run typecheck
npm run lint
npm test

Commit messages follow Conventional Commits: feat: · fix: · docs: · refactor:

License

MIT