unic

unic is a Go-based TUI for browsing and operating AWS resources from the terminal. It combines a Bubble Tea application, Cobra-based CLI commands, and AWS SDK v2 clients behind a context-aware authentication layer.

What It Does

Browse AWS services from a single terminal UI
Switch between credential, assume-role, and SSO contexts
Export shell environment variables for the active context
Drill down into resources with filters, detail views, and action screens
Open a context-aware keyboard shortcut help screen with ?
Show animated loading indicators while async AWS data is being fetched
Perform operational workflows such as SSM sessions, RDS control, Route53 record changes, ECS rollout inspection/exec, IAM access key rotation, and Bedrock API key management
Press i from the service picker to enter Inspector mode, then run either the Security Inspector workflow for built-in findings or the Checklist Inspector workflow for YAML-driven readiness checks across databases, network resources, DNS, logging, secrets, and baseline posture. Checklist files can be loaded from the in-TUI picker or preloaded with --checklist <path>

Documentation Map

This is the closest structure to a "harness-like" doc hub in this repository: one entry document with focused reference docs behind it.

Tech Stack

Go 1.22+
TUI: Bubble Tea, Bubbles, Lip Gloss
CLI: Cobra
AWS: aws-sdk-go-v2
Config: gopkg.in/yaml.v3
Logging: structured file logging under ~/.config/unic/logs/
Testing: Go testing, table-driven tests, mocked AWS clients

Installation

Homebrew

brew tap DevopsArtFactory/unic
brew install unic

Install Script

curl -sSL https://raw.githubusercontent.com/DevopsArtFactory/unic/main/install.sh | sh

Set INSTALL_DIR to override the default install path.

Build From Source

git clone https://github.com/DevopsArtFactory/unic.git
cd unic
make build

CLI Usage

Run the TUI

unic
unic --profile my-profile
unic --region ap-northeast-2
unic --checklist ./checklists/readiness.yaml   # optional: pre-load a checklist at startup
unic --verbose

Config/bootstrap

unic init
unic init --force
unic update

Shell environment helpers

# Print exports for current context
unic env

# Print exports for a named context
eval "$(unic env prod-admin)"

# Interactively choose/setup a context and copy exports to clipboard
unic context setup

# Set a display order for a context
unic context order prod-admin 10

# Or open reorder mode, then move the selected context with arrow keys and save
unic context order

# Clear current context and copy cleanup commands to clipboard
unic context unset

unic context setup writes its prompts to stderr and copies the generated shell commands to the clipboard. unic env prints shell commands to stdout so it can be used with eval. Both flows now include a UNIC_CONTEXT marker in the generated exports so the TUI can show which shell context is currently active. Contexts can be prioritized in the setup picker with an order field in config. In the CLI unic context setup flow, the picker now filters contexts, SSO accounts, and SSO roles as you type, with arrow-key navigation and Enter to confirm. Use unic context order to open reorder mode, choose a context with ↑/↓ or j/k, press Enter to start moving it, then press Enter again to save. unic context order <name> <number> still works for direct updates.

Configuration

Primary config path:

~/.config/unic/config.yaml

Legacy Flat Format

default_profile: my-profile
default_region: ap-northeast-2

Context-Based Format

current: dev-sso

defaults:
  region: ap-northeast-2

contexts:
  - name: dev-sso
    order: 10
    profile: my-sso-profile
    region: ap-northeast-2
    auth_type: sso
    sso_start_url: https://example.awsapps.com/start

  - name: dev-sso-123456789012-developerrole
    profile: my-sso-profile
    region: ap-northeast-2
    auth_type: sso
    sso_start_url: https://example.awsapps.com/start
    sso_account_id: "123456789012"
    sso_role_name: DeveloperRole

  - name: prod-admin
    order: 20
    profile: base-profile
    region: us-east-1
    auth_type: assume_role
    role_arn: arn:aws:iam::123456789012:role/Admin
    external_id: optional-external-id

  - name: local-dev
    profile: local-dev
    region: ap-northeast-2
    auth_type: console_login

  - name: staging
    profile: staging
    region: eu-west-1
    auth_type: credential

Auth Types

Auth Type	Meaning	Required Fields
`credential`	Use shared AWS profile credentials	`profile`
`console_login`	Run `aws login` during `unic context setup`, then use the resulting profile-backed console credentials	`profile`
`assume_role`	Assume a role from a base profile	`profile`, `role_arn`
`sso`	Use AWS IAM Identity Center / SSO	`profile`, `sso_start_url`, and for concrete contexts `sso_account_id`, `sso_role_name`

Optional context fields:

Field	Meaning
`order`	Lower values appear first in the context setup picker. Contexts without `order` fall back after ordered entries in their existing file order.

Resolution priority:

CLI flags > selected context > config defaults > hardcoded default (us-east-1)

Context ordering:

Lower order values appear first
Contexts without order appear after ordered contexts
Contexts with the same order keep their file order

Current Features

AWS Service Catalog

Service	Feature
EC2	SSM Session Manager
EC2	Security Group Browser
VPC	VPC Browser
VPC	Reachability Analyzer
RDS	RDS Browser
Route53	Route53 Browser
Secrets Manager	Secrets Browser
CloudWatch	Metrics Viewer
CloudWatch Logs	Logs Browser
ECS	ECS Browser & Exec
S3	S3 Browser
Lambda	Lambda Browser
Bedrock	API Key Manager
IAM	IAM User Browser
IAM	ListAccessKeys
IAM	RotateAccessKey

Inspector Mode

Workflow	Status	Notes
Security Inspector	Ready	Runs built-in rule packs and opens severity-filtered findings
Checklist Inspector	Ready	Runs a YAML checklist and reports pass/fail per check with resource context and mismatch details

Security Inspector ships built-in rule packs for Security Group exposure, RDS encryption/public access/backups and public snapshot sharing, IAM access key age/root-account hardening/wildcard policies, Secrets Manager rotation age, S3 public access/Block Public Access/versioning, CloudTrail baseline coverage, GuardDuty and AWS Config baseline controls, and ElastiCache for Valkey encryption/backup/access-control checks.

Checklist Inspector can load a YAML file either from the Inspector-mode file picker or from --checklist at startup, and currently supports:

rds for expected DB instance state such as status, engine, class, Multi-AZ, encryption, public access, and backup retention
security_group for required or forbidden ingress/egress rule matchers
secret for rotation state, KMS key ID, and required JSON value keys
hosted_zone for hosted zone existence and private/public scope checks
route53_record for DNS record existence, type, TTL, values, and alias target checks within expect.zone
vpc for VPC existence, CIDR, default-VPC posture, and subnet-count checks
subnet for subnet existence, optional expect.vpc scoping, CIDR, availability zone, and minimum available-IP checks
cloudwatch_log_group for log-group existence and retention-days checks
cloudtrail_baseline, guardduty_baseline, config_baseline, and elasticache_valkey_baseline for checklist-driven pass/fail wrappers around the built-in baseline security scanners

Minimal checklist example:

name: Production Readiness
checks:
  - type: rds
    resource: prod-db
    expect:
      publicly_accessible: false
      storage_encrypted: true
      backup_retention_days: 7

  - type: security_group
    resource: sg-web
    expect:
      ingress_absent:
        - protocol: tcp
          from_port: 22
          to_port: 22
          cidr: 0.0.0.0/0

  - type: secret
    resource: prod/app
    expect:
      rotation_enabled: true
      value_keys:
        - username
        - password

  - type: route53_record
    resource: api.example.internal
    expect:
      zone: example.internal
      record_type: A
      alias_target: internal-alb-123.ap-northeast-2.elb.amazonaws.com

  - type: vpc
    resource: main-vpc
    expect:
      cidr: 10.0.0.0/16
      subnet_count: 2

  - type: cloudwatch_log_group
    resource: /aws/ecs/app
    expect:
      retention_days: 30

  - type: cloudtrail_baseline
    resource: cloudtrail

TUI Navigation

Global

Key	Action
`j` / `k`, `↑` / `↓`	Move selection
`Enter`	Select / drill down
`Esc`	Go back
`q`	Quit from top-level screens
`H`	Jump to service list
`i`	Enter Inspector mode from the service list
`C`	Open context picker
`/`	Toggle filter mode on supported screens
`?`	Toggle context-aware shortcut help
`Ctrl+C`	Force quit

Service-specific highlights

Area	Keys
EC2 SSM	`r` refresh, `Enter` connect
Security Groups	`a` add rule, `d` delete rule, `Tab` switch ingress/egress
Reachability Analyzer	Region select first, `←`/`→` or `Tab` change type, `/` filter, `Enter` advance, `Tab`/`↑`/`↓` move config fields, `←`/`→` protocol, `r` rerun
RDS	`s` start, `x` stop, `f` failover, `r` refresh
Route53	`c` create, `e` edit, `d` delete
IAM Key Rotation	`r` rotate, `c` copy exports, `a` apply and verify, `d` deactivate old key, `x` delete old key
Bedrock API Keys	`c` create, choose current IAM user or another user, `r` rotate secret, `d` delete, type the IAM user/key ID to confirm, `c` copy one-time key without printing it, `e` copy `AWS_BEARER_TOKEN_BEDROCK` export
CloudWatch Metrics	preset-driven metric list/detail flow, `/` filter, `space` select related series, `g` preset cycle, `t/p/s` range-period-stat controls, `r` refresh, in-terminal single-series and comparison charts
CloudWatch Logs	log groups/streams load 10 at a time, `n` load more, `1`-`6` time presets, `t` live tail, `f` filter pattern, `w` wrap toggle, `h/l` horizontal scroll
ECS Exec	`r` refresh, `Enter` drill down / exec
ECS Rollout / Exec	cluster/service lists support refresh and drill-down, service detail shows deployments/task definition images/events, `Enter` continues into tasks and exec
Inspector Mode	`i` open mode from the service list, `Enter` open the selected workflow, `l` open the checklist file picker
Security Inspector	`r` run/rescan, `1`-`5` severity filter, `Enter` finding detail
Checklist Inspector	`l` load or switch checklist files, `r` run/rerun the loaded checklist, `Enter` result detail
Context Picker	`a` add context, type or `/` filter, `s` setup selected context and quit, `y` copy selected exports and quit, `u` clear shell context and quit with a final confirmation message
Lambda	`Enter` invoke, `d` detail, `l` view CloudWatch Logs, `/` filter, `r` refresh

Shared list filters now use fuzzy matching with inline match highlighting. While filter mode stays active, ↑/↓ continue to move through the filtered results without requiring an extra Enter first. Filtering is currently available on EC2 instances, IAM users, VPCs, subnets, RDS instances, Route53 zones/records, CloudWatch metrics, CloudWatch log groups/streams, Secrets Manager resources, ECS clusters/services, S3 buckets/objects, Lambda functions, Bedrock API keys, and the context picker.

Bedrock API key management uses the active unic AWS context and IAM service-specific credential APIs for bedrock.amazonaws.com. The TUI lists long-term Bedrock API key metadata, opens a detail screen for inspection, defaults new key generation to the current IAM user when that user can be inferred from caller identity, and keeps another-user generation as an explicit option. Creation supports an optional expiration period, where blank or 0 means no expiration, rotates secrets with a one-time result screen, and deletes keys only after typed confirmation. Generated and rotated key values are intentionally copy-only and are not printed to the terminal; on the result screen, c copies the key and e copies export AWS_BEARER_TOKEN_BEDROCK=....

Reachability Analyzer starts with a region selection step, defaults to the current context region, and now surfaces the AWS-documented source and destination resource types that unic supports: EC2 instances, Internet gateways, Network interfaces, Transit gateways, Transit gateway attachments, Virtual private gateways, VPC endpoint services, VPC endpoints, VPC peering connections, plus IP addresses as destinations. The source and destination pickers support type tabs, keyword filtering, IPv4 destination validation, and automatic cleanup of temporary Network Insights resources after each analysis. During analysis, the loading screen shows a vertical source-to-destination flow and intent summary, and the result view renders path hops and findings in a more readable layout.

Development

go run ./cmd/unic
go test ./...
make build

Release artifacts are produced through GoReleaser and the dist/ outputs.

Community Standards

Issue Bot

Comment on an issue with:

Command	Action
`@unic-bot: assign me`	Assign the issue to yourself

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

unic

What It Does

Documentation Map

Tech Stack

Installation

Homebrew

Install Script

Build From Source

CLI Usage

Run the TUI

Config/bootstrap

Shell environment helpers

Configuration

Legacy Flat Format

Context-Based Format

Auth Types

Current Features

AWS Service Catalog

Inspector Mode

TUI Navigation

Global

Service-specific highlights

Development

Community Standards

Issue Bot

Contributors

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

unic

What It Does

Documentation Map

Tech Stack

Installation

Homebrew

Install Script

Build From Source

CLI Usage

Run the TUI

Config/bootstrap

Shell environment helpers

Configuration

Legacy Flat Format

Context-Based Format

Auth Types

Current Features

AWS Service Catalog

Inspector Mode

TUI Navigation

Global

Service-specific highlights

Development

Community Standards

Issue Bot

Contributors