aws-cli-tui

Search-first terminal UI for AWS resource types. The interactive homepage groups Smithy List, Get, and Describe operations into resources such as Agent runtime, Gateway, Table, and Topic.

The complete operation catalog is generated from the public aws/api-models-aws Smithy JSON AST. Interactive users search resource names with one fuzzy, typo-tolerant no-space token. Exact normalized matches rank first. AWS service names are not a navigation level; the resolved service appears beside each resource and on detail views.

Demo

Click the animation to open the MP4. The screenshots and recording were captured with TUI Harness using synthetic AWS responses; they contain no customer or account data.

Fuzzy resource search

Paginated List view

Focusable JSON detail

Related resources

Requirements

• Node.js 20 or later
• AWS CLI v2 on PATH
• Configured AWS credentials

Install from GitHub

Install the packaged GitHub release:

npm install --global \
  https://github.com/jariy17/aws-cli-tui/releases/download/v0.3.0/aws-cli-tui-0.3.0.tgz

To install the latest main branch instead, force npm to materialize Git dependencies rather than linking its temporary checkout:

npm install --global --install-links github:jariy17/aws-cli-tui

If the project was previously installed with npm link, unlink that development installation once before switching:

npm unlink --global aws-cli-tui
npm install --global --install-links github:jariy17/aws-cli-tui

Then launch it with an AWS CLI profile and region:

awstui --profile my-profile --region us-west-2

The tool uses the AWS CLI's existing credential chain. Configure credentials first with aws configure, aws configure sso, or your usual profile setup.

Install from a clone

git clone https://github.com/jariy17/aws-cli-tui.git
cd aws-cli-tui
npm ci
npm link

awstui --profile my-profile --region us-west-2

To run without creating a global link:

npm start -- --profile my-profile --region us-west-2

Type a no-space resource search such as agentruntime, gateway, tables, or buckets. Typos and abbreviated subsequences such as agentruntmie or agntrntm are supported. API operation names such as listagentruntimes are reserved for the direct awstui list and awstui get commands rather than the interactive homepage.

The search view uses the same flat table layout as List pages. It reserves fixed rows and shows Resource, Service, List, and Read columns. List and Get/Describe operations for the same normalized resource and AWS CLI service are combined into one row. Enter runs the resource's primary List operation, opening its modeled input form first when required.

Resources that only have a Get/Describe operation remain visible in the default search with Read: Yes, but are dimmed because there is no primary List operation to open. Running awstui get without an API token opens the same resource-oriented search in read mode.

Search and List tables fill the available terminal height regardless of result count. The bottom three rows are reserved for status, help, and the hidden debug line.

Views use React Router's in-memory URL patterns. Routes identify resource search, operation inputs, List pages, selected entries, resource details, and related resources. Back restores the previous route state, and stale asynchronous responses cannot replace a newer view.

Plain queries search resources. Prefix a no-space query with service: to search by service instead; resource: remains accepted as an explicit resource scope:

service:sns
resource:topic

Resource rows use Smithy resource relationships where available and group operations by resource name otherwise. Search accepts singular and plural names from the primary List and Read operations.

Direct commands

# List API; returns the first API page as JSON
awstui list agentruntime --profile my-profile --region us-west-2

# List API with required Smithy inputs
awstui list memoryrecords \
  --input memoryId=my-memory-id \
  --input namespace=/users/example \
  --profile my-profile \
  --region us-west-2

# Get/Describe API; repeat --input for required identifiers
awstui get agentruntime \
  --input agentRuntimeId=my-runtime-id \
  --profile my-profile \
  --region us-west-2

List operations open an input view only for unresolved required Smithy inputs. Optional inputs are omitted initially, pagination tokens are managed internally, and modeled defaults are included automatically. Press E on a List page to configure its optional Smithy inputs and rerun from page 1. Booleans and enums render as filterable dropdowns. Left and Right move between API pages. Press / on a List page to fuzzy search only the rows already loaded for that page; this never makes another AWS request.

Pressing Enter on a List row opens a compatible Get/Describe detail API when its Smithy-declared inputs can be filled exactly from the selected row and the original List request. Selected-row values take precedence. For example, a DynamoDB table name from ListTables is passed to DescribeTable as TableName; GetMemoryRecord combines a selected memoryRecordId with the memoryId entered for ListMemoryRecords.

TUI controls

• Type letters or numbers: update the global fuzzy resource search
• Up/Down: select a matching resource, list row, or JSON entry
• Left/Right: move between resource, API, or detail pages
• Enter: run the selected resource's List API or open/get a selected row
• / outside the main search: fuzzy filter the current view
• E on a List page: configure optional inputs and rerun from page 1
• R on a resource detail page: open its related resources
• Escape: clear search or go back

Resource views keep the navigation route and resolved Smithy keys in the header. For example:

>_ AWS TUI · Memory › Sessions       Amazon Bedrock AgentCore · Page 2/2
ListSessions · memoryId=mem-123 · actorId=actor-456 · maxResults=100

The detail page shows:

• Friendly AWS service title and Smithy operation in the header
• Syntax-colored, pretty-printed resource or Get response JSON
• Focusable JSON entries, with verified ARN values available to open
• Related child collections whose List inputs can inherit a parent identifier

Related resources prefer explicit Smithy resources relationships. When a model does not declare a child resource, the catalog conservatively offers a List operation only when it shares the modeled parent resource, belongs to the same AWS service family, and can inherit a parent identifier exactly. For example, GetMemory can open ListMemoryRecords, while GetPaymentManager follows the explicit Smithy child relationship to ListPaymentConnectors. Press R, or move to the related-resources entry and press Enter, then select the child collection and enter any inputs that were not inherited.

On a detail page, only ARNs that resolve to an unambiguous read operation are highlighted and selectable. Other ARN strings, such as a DynamoDB IndexArn without a direct index read API, remain ordinary JSON. The resolver checks the current public Smithy model on GitHub for the source and target services, follows aws.api#arnReference to a resource read operation when available, and otherwise uses a conservative ARN/service/Get-or-Describe fallback. Models are conditionally cached with GitHub ETags, so every drill-through checks for a newer model without redownloading unchanged JSON.

Smithy model directory names and AWS CLI service commands are stored separately. For example, the public model lives under dynamodb-streams, while execution correctly uses aws dynamodbstreams.

Refresh the Smithy catalog

Clone the public model repository, then regenerate:

git clone --depth 1 --filter=blob:none --sparse \
  https://github.com/aws/api-models-aws.git /tmp/api-models-aws
git -C /tmp/api-models-aws sparse-checkout set models
npm run models:generate -- /tmp/api-models-aws

The generated catalog records the source repository and commit SHA.

Development

npm run typecheck
npm test
npm run build

Open a specific AWS operation

Replace aws with awstui to open a modeled List, Get, or Describe operation with its inputs already populated:

awstui ec2 describe-instances \
  --filters 'Name=tag:Team,Values=api,worker' \
  --region us-west-2 --profile my-profile

awstui lambda get-function --function-name my-function

awstui dynamodb get-item --table-name Example \
  --key '{"pk":{"S":"example"}}' --consistent-read

awstui s3api list-objects-v2 --bucket example-bucket --prefix logs/

Service names, operation names, flags, booleans (including --no-…), lists, nested structures, maps, and enums come from the generated Smithy catalog and input-shape graph. Required inputs you omit open the input form. Use awstui SERVICE OPERATION --help for the modeled flags. Inputs accept JSON, AWS shorthand, file:// values, and --cli-input-json or --cli-input-yaml; explicit flags override values in an input document.

Global options are generated separately from the public AWS CLI cli.json metadata, since Smithy service models do not define CLI globals. Profiles, regions, endpoint overrides, signing/TLS options, timeouts, and binary format are carried into execution. --query applies JMESPath to displayed results. --page-size, --max-items, and --starting-token use the AWS CLI paginator for operations with modeled pagination; the TUI carries opaque CLI tokens forward without treating them as service tokens. Without those flags, it fetches one service page at a time.

The TUI always consumes JSON and supplies its own display and input controls; --output, --color, pager, and auto-prompt flags do not switch its renderer. These entry points require a terminal. Existing awstui list and awstui get search commands continue to return JSON when given an API search token.

Compatibility covers the bundled modeled read operations, rather than every AWS CLI customization. Resource mutations, s3 transfer commands, wait, logs tail, custom positional file-output arguments, and CLI plugins are not implemented by this entry point. An operation still needs to be available in your installed AWS CLI and permitted by your AWS credentials.

Regenerating CLI metadata and checking the terminal UI

npm run models:generate refreshes both the operation catalog and the nested input-shape graph, recording the public model repository and commit. To refresh AWS CLI global options from an AWS CLI source checkout:

npm run models:cli-options -- /path/to/aws-cli/awscli/data/cli.json 2.x.y
npm run build

The terminal verification script uses an independently installed, built TUI Harness through its public library interface. It creates temporary synthetic AWS responses; it does not contact AWS:

npm run build
TUI_HARNESS_PATH=/path/to/tui-harness npm run test:tui
# Optional: save synthetic screenshots
TUI_HARNESS_PATH=/path/to/tui-harness \
  TUI_SCREENSHOTS=/tmp/awstui-screens npm run test:tui

The checks cover resource search, List-to-detail navigation, related resources, modeled flags, CLI pagination tokens, and required-input routing at 140×40, 80×24, and 60×18 terminal sizes.