Skip to content

README.md

Latest commit

 

History

History
283 lines (209 loc) · 8.38 KB

README.md

File metadata and controls

283 lines (209 loc) · 8.38 KB

unic

unic is a Go-based TUI (Terminal User Interface) tool for browsing and managing AWS resources in the terminal.

It manages authentication contexts (SSO or STS AssumeRole) via ~/.config/unic/config.yaml and provides drill-down exploration of AWS services registered in the catalog.

Tech Stack

  • Go (1.22+)
  • TUI: Bubbletea + Lipgloss + Bubbles
  • CLI: Cobra
  • AWS SDK: aws-sdk-go-v2
  • Config: gopkg.in/yaml.v3
  • Concurrency: goroutines + errgroup
  • Error handling: fmt.Errorf / errors

Installation

Homebrew (macOS/Linux)

brew tap DevopsArtFactory/unic
brew install unic

Install Script (macOS/Linux)

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

Set INSTALL_DIR to change the install location (default: /usr/local/bin).

Build from Source

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

Usage

# Enter TUI mode
unic

# Specify profile/region
unic --profile my-profile
unic --region ap-northeast-2

# Enable verbose debug logging (writes to ~/.config/unic/logs/unic.log)
unic --verbose
unic -v

# Initialize config file
unic init                      # Create default config
unic init --force              # Overwrite existing config

# Update to latest version
unic update                    # Auto-detects install method (brew vs binary)

# Print shell exports for the current context
eval "$(unic env)"

# Print shell exports for a named context
eval "$(unic env staging-creds)"

# Interactively select/setup a context, set it current, and copy exports to clipboard
unic context setup

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

Configuration

~/.config/unic/config.yaml (created via unic init or auto-generated on first run)

Legacy Format (Flat)

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

Context-Based Format

current: dev-sso

defaults:
  region: us-east-1

contexts:
  # SSO base context for one-step setup.
  # `unic context setup` will log in, let you pick an account/role,
  # then create or reuse a concrete context automatically.
  - name: dev-sso
    region: ap-northeast-2
    profile: my-sso-profile
    auth_type: sso
    sso_start_url: https://my-sso-portal.awsapps.com/start

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

  # Assume Role (cross-account)
  - name: prod-assume
    region: us-east-1
    auth_type: assume_role
    profile: base-profile
    role_arn: arn:aws:iam::987654321098:role/CrossAccountRole
    external_id: optional-external-id

  # Credential profile
  - name: staging-creds
    region: eu-west-1
    auth_type: credential
    profile: staging

Auth Types

Auth Type Required Fields Description
sso sso_start_url, sso_account_id, sso_role_name AWS SSO portal login with token caching
credential profile Uses ~/.aws/credentials profile directly
assume_role profile, role_arn Assumes a cross-account role from a base profile

Priority: CLI flags (--profile, --region) > context settings > config defaults > hardcoded defaults (us-east-1)

One-Step Context Setup

unic context setup is designed for interactive setup:

unic context setup

Behavior:

  • Prompts and progress messages go to stderr
  • Shell export / unset commands are copied to the clipboard
  • Credential contexts export AWS_PROFILE and region vars
  • Assume-role contexts export temporary STS credentials
  • SSO base contexts can log in, list accessible accounts and roles, and save a concrete context automatically
  • ~/.aws/credentials is not modified by this flow

unic context unset clears the current context from ~/.config/unic/config.yaml and copies AWS cleanup commands to the clipboard so you can quickly reset your shell environment.

Currently Implemented Features

Service Feature Status
EC2 SSM Session Manager (connect to running, SSM-managed instances) ✅ Implemented
EC2 Security Group Browser (list/filter SGs, view rules, add/delete rules with confirmation) ✅ Implemented
VPC VPC Browser (VPCs → Subnets → Available IPs with reserved-IP exclusion) ✅ Implemented
RDS RDS Browser (list, start/stop, failover, Aurora cluster support, auto-polling) ✅ Implemented
Route53 DNS Browser (Hosted Zones → Records → Record Detail, create/edit/delete A/CNAME, change status polling) ✅ Implemented
CloudWatch Logs Log Browser (Log Groups → Streams → Events, live tail with 2s poll, time range presets, filter patterns, log level highlighting) ✅ Implemented
Secrets Manager Secrets Browser (list secrets, view key-value pairs or raw values) ✅ Implemented
IAM IAM User Browser (lightweight username pages, background filter expansion, detail drill-down) ✅ Implemented
IAM Access Key Browser (list keys with status, age, last used) ✅ Implemented
IAM Access Key Rotation (create → verify/apply → deactivate → delete) ✅ Implemented

TUI Key Bindings

Global

Key Action
j/k or ↑/↓ Navigate list
Enter Select item
Esc Go back one screen
q Quit (on service list)
H Jump to home (service list)
C Open context switcher
/ Toggle filter mode
Ctrl+C Force quit

EC2 SSM Session

Key Action
r Refresh instance list
Enter Connect to instance

Security Groups

Key Action Screen
/ Filter security groups List
r Refresh list List
Enter View inbound/outbound rules List
Tab Switch between Inbound/Outbound section Detail
j/k or ↑/↓ Navigate rules Detail
a Add rule (multi-step form) Detail
d Delete selected rule (type-to-confirm) Detail

RDS Detail

Key Action Condition
s Start database Instance/cluster is stopped
x Stop database Instance/cluster is available
f Failover database Multi-AZ standalone or Aurora cluster
r Refresh status Always

IAM Users

Key Action Screen
/ Filter IAM users and continue loading remaining usernames in background List
n Load next page of IAM users List
Enter View groups, policies, and access keys List

IAM Access Key Rotation

Key Action Screen
r Rotate access key Key detail (RotateAccessKey mode)
c Copy new key as export commands Rotation result
a Apply new key to ~/.aws/credentials and verify Rotation result
d Deactivate old key Rotation result
x Delete old inactive key Rotation result

CloudWatch Logs

Key Action Screen
/ Filter log groups/streams List
Enter Drill into streams/view logs List
1-6 Time range preset (5m/15m/1h/6h/24h/7d) Viewer
t Toggle live tail (2s poll) Viewer
f Enter filter pattern Viewer
n Load more (older events) Viewer
PgUp/PgDn Page scroll Viewer

Context Switcher

Key Action
Enter Switch to selected context
a Add new context (wizard)
/ Filter contexts
Esc Back

Filtering

Available on: EC2 instances, IAM users, VPC/Subnets, RDS instances, Route53 zones/records, CloudWatch Log Groups/Streams, Secrets Manager, Context Switcher. Press / to enter filter mode, type to search, Esc or Enter to exit filter mode.

Documentation

License

This project is licensed under the terms in LICENSE.

Issue Bot

Comment on any issue to interact with @unic-bot:

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

Community Standards

Maintainers

  • Add maintainers here.