infra-cli

infra-cli is a pluggable infrastructure management tool designed to wrap common DevOps tools (Terragrunt, Terraform, Ansible, Packer, etc.) into a single, unified interface. It simplifies complex workflows through sensible conventions and centralized configuration.

使用文档

macOS 安装

新机器请按顺序执行（需先装好命令行工具与 Homebrew，再用 pipx 安装本 CLI）：

# 1. Apple Command Line Tools（弹出对话框时按提示完成）
xcode-select --install

# 2. Homebrew
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
# Apple Silicon 安装结束后按提示把 brew 加入 PATH，例如：
#   echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
#   eval "$(/opt/homebrew/bin/brew shellenv)"

# 3. pipx
brew install pipx
pipx ensurepath
# 重新打开终端，或: source ~/.zprofile / source ~/.zshrc

# 4. infra-cli
pipx install infra-cli
# 可选 AWS 相关依赖: pipx inject infra-cli '.[aws]'

infra doctor

从本地 checkout 安装：git clone … && cd infra-cli && pipx install .

装好后可用 infra setup 引导本机开发环境（会保留已有配置，详见下方 Quick Start）。

🚀 Key Features

• Unified Interface: A single command (infra) to manage multiple infrastructure tools.
• Plugin Architecture: Easily extensible logic for different tools.
• Convention over Configuration: Default directory structures that "just work."
• Centralized Config: Manage all tool settings in one place (~/.infra/config.yaml).
• AWS SSO Integration: Seamlessly handles authentication and profile generation.
• Local Environment Setup: Automate the configuration of your macOS or Ubuntu dev environment.

🛠 Supported Plugins

• setup: Bootstrap your local development environment (macOS/Ubuntu).
• ansible: Wrapper for ansible-playbook with automatic project scaffolding.
• aws: SSO login, landing zones, and cross-account commands (infra aws <service> <verb>), including EC2 / RDS / ElastiCache inventory and SSM password audits.
• packer: Build and validate machine images consistently.
• terraform / tf: Run Terraform under $INFRA_REPO/terraform/sites/<env>/<stack>; scaffold creates terraform/{sites,modules}.
• terragrunt / tg: Run Terragrunt under $INFRA_REPO/terragrunt/<env>/<account>/<region>/<stack> (sibling of terraform/).
• github: Manage repository settings and scaffolding.
• slack: Send notifications to Slack webhooks.
• server: Local, read-only HTML command reference (infra server start).
• work: Agent work mode — skills, connectors, partners, session context, plan/run, optional MCP (infra work mcp) and LLM explain.
• eol: Product end-of-life scan against endoflife.date.

🏁 Quick Start

Installation

See 使用文档 above for a full fresh-macOS path (xcode-select → Homebrew → brew install pipx → pipx install infra-cli).

Existing dotfiles and brew/apt packages are preserved by infra setup.

pipx install infra-cli              # or: pipx install .
pipx inject infra-cli '.[aws]'      # optional extras
# First infra run creates ~/.infra/env.sh (adds ~/.local/bin to PATH). Then:
source ~/.infra/env.sh              # or open a new shell after: pipx ensurepath
infra doctor
infra setup doctor

Upgrade infra-cli: infra setup upgrade-cli --pypi · from checkout: --from-path ~/…/infra-cli · after setup run: infra setup run --upgrade-cli --pypi

Basic Usage

# Full workstation bootstrap (all playbook tags)
infra setup

# Layered install (default profile for `run`: core)
infra setup run
infra setup run --profile cloud
infra setup doctor
infra setup list

# Targeted component install (same playbook, fixed tags)
infra setup packer
infra setup aliyun      # also: infra setup alicloud
infra setup aws
infra setup terraform
infra setup trivy
infra setup k8s

# Login to AWS SSO (picks a landing zone when several are configured)
infra aws login

# Re-login before a long terraform/terragrunt run to refresh the SSO token
infra aws login --lz prod

# Log out of that org's SSO session and expire cached role credentials
infra aws logout
infra aws logout --lz prod
infra aws logout --all

# Pick a profile for the current shell
eval "$(infra aws select)"

# Alibaba Cloud CloudSSO (requires Alibaba Cloud CLI 3.0.271+)
# infra aliyun  = China Website (aliyun.com)  · ALIBABA_CLOUD_ACCOUNT_TYPE=Domestic
# infra alicloud = International Website (alibabacloud.com) · International
# Accounts are not interchangeable — use the matching subcommand.
infra aliyun landing-zones add prod \
  https://signin-******.alibabacloudsso.com/device/login cn-hangzhou
infra aliyun login --lz prod
infra alicloud landing-zones add prod \
  https://signin-******.alibabacloudsso.com/device/login ap-southeast-1
infra alicloud login --lz prod
eval "$(infra aliyun select)"
eval "$(infra alicloud select)"
infra aliyun profiles
infra alicloud profiles

# Inventory EC2 / RDS / ElastiCache across SSO accounts
infra aws ec2 list
infra aws rds list --excel
infra aws elasticache list --excel

# Inspector HIGH/CRITICAL findings for ECR images
infra aws ecr issues

# Audit SSM SecureString strength (skips prod by default)
infra aws ssm audit --profile-filter '-admin$'

# Run an Ansible playbook
infra ansible playbook site.yml

# Terraform / Terragrunt share one INFRA_REPO, split at the top level:
#   $INFRA_REPO/terraform/…   $INFRA_REPO/terragrunt/…
# Omit the verb → plan; -y with no verb → apply -auto-approve. Auto-init when needed.
infra terraform scaffold ~/github.com/acme/infra
infra terragrunt scaffold -e dev -a personal -r us-east-1 -s vcn ~/github.com/acme/infra
export INFRA_REPO=~/github.com/acme/infra
infra terraform -e stg -s platform/example
infra tg -e prod -s workload/us-east-1/vpc -ss network/us-east-1/tgw plan
infra tf -e prod -s platform/devops -t module.vpc
infra terraform -y -e stg -s platform/example
infra tf apply -e prod -s platform/devops -y
# After destroy: cleans .terraform locally and prints `rm -rf` for the stack; --rm deletes it
infra tf destroy -e stg -s platform/example -y
infra tf destroy -e stg -s platform/example -y --rm

# Check configuration
infra config list

# Local HTML cheatsheet of every command (needs: pip install 'infra-cli[server]')
infra server start
infra server start --no-browser -p 9000

# Agent work mode (skills + connectors + MCP; mutate needs --yes)
infra work context
infra work skills
infra work plan "find AWS cost waste"
infra work run --skill cost-review --dry-run
infra work mcp   # stdio MCP for Cursor / Claude / Doubao connectors

Every command accepts -h / --help (GNU long options; short flags where they do not clash). infra with no arguments prints the same overview as infra -h. Nested groups also print help when invoked with no verb (infra server, infra aws, infra config, …).

infra -h
infra aws login -h
infra aliyun login -h
infra alicloud login -h
infra server -h
infra server start -h

Naming recommendations (optional)

infra-cli suggests — but never enforces — a consistent naming pattern for cloud accounts and CLI profiles. Existing account aliases and ~/.aws/config profile names keep working unchanged.

Why env as suffix: the last - segment is easy to extract programmatically and aligns with canonical env tiers (prod, stg, test, dev, sandbox).

Directory layout vs cloud alias: Terragrunt on-disk account dirs stay short (terragrunt/dev/personal/...); the cloud account alias may add the env suffix (personal-dev). Terraform sites put env in the path (terraform/sites/dev/platform) — stack names should be workload-only, not platform-dev.

infra tg scaffold and infra tf scaffold print examples after a successful run. See also src/infra/templates/aws_sso/config.ini.

⚙️ Configuration

infra-cli uses a YAML configuration file located at ~/.infra/config.yaml.

Managing Config via CLI

You can get or set configuration values directly:

# Set a default user name for the setup plugin
infra config set setup.user_name=your_name

# View current configuration
infra config list

Manual Configuration

The default config.yaml is generated on first run with sensible defaults. You can customize per-plugin settings like region, env, or extra_args.

Optional AWS extras (Excel export + zxcvbn scoring):

pipx inject infra-cli '.[aws]'
# or, from a checkout during install:
pipx install '.[aws]'

AWS inventory and audit

Commands follow the AWS CLI layout (aws <service> <verb>), but each verb can scan every profile in ~/.aws/config (typically generated by infra aws login). Accounts without credentials are skipped instead of aborting the whole run.

infra aws --help
infra aws login --help
infra aws logout --help
infra aws profiles --help
infra aws ec2 list --help
infra aws rds list --help
infra aws elasticache list --help
infra aws ssm audit --help
infra aws ssm search --help
infra aws ecr login
infra aws ecr issues
infra aws ecr issues --format json --filter '*base*'

ECR image findings

Lists HIGH/CRITICAL Inspector findings for ECR container images in the selected account (infra aws ecr issues). Prefer this over a separate top-level scan command.

infra aws ecr issues
infra aws ecr issues --profile my-org-admin -r us-east-1 --format json

To add another service, drop a module in src/infra/plugins/aws/services/ that exports SERVICE (the AWS CLI service name) and app (a Typer group). It is picked up automatically. Runtime extras can also call register_service(name, app).

Agent work mode (infra work)

Productivity-agent pattern: skills + connectors + partners + context → plan → run. Optional AI explain via multi-provider config (work.ai).

infra config set work.ai.enabled=true
infra work ai doctor
infra work ai status --provider claude
infra work run --skill cost-review --explain --provider deepseek
infra aws cost waste --format json | infra work explain --provider doubao

Providers: claude (Claude Code settings), cursor, copilot, gemini, codex, deepseek, doubao, plus legacy openai_compat. Keys stay in env or tool settings — never in config.yaml. OAuth session files are never read. read_settings defaults false; outbound base_url must be https:// with redirects blocked.

MCP snippet:

{
  "mcpServers": {
    "infra-work": {
      "command": "infra",
      "args": ["work", "mcp"]
    }
  }
}

Details: src/infra/templates/work/README.md.

Alibaba Cloud CloudSSO

Same aliyun CLI binary and CloudSSO configure flow for both sites; accounts, billing, and some product endpoints are not interchangeable. Implementation is shared under src/infra/plugins/alibaba/ (create_site_app(site)); only the public verbs and site metadata differ.

Landing-zone caches are separate (~/.config/infra/aliyun/ vs ~/.config/infra/alicloud/). Sign-in URLs still use *.alibabacloudsso.com (including accelerated URLs). One CLI profile maps to one RD account + one access configuration.

infra aliyun --help
infra alicloud --help
infra aliyun login --help
infra alicloud login --help
eval "$(infra aliyun select)"   # also exports ALIBABA_CLOUD_ACCOUNT_TYPE=Domestic
eval "$(infra alicloud select)" # International

EC2 inventory

Lists instances across accounts (aws ec2 describe-instances, cross-account). Terminated instances are omitted unless you pass --include-terminated.

infra aws ec2 list
infra aws ec2 list --profile my-org-admin --region us-east-1 --excel --json ec2.json
infra aws ec2 list --profile-filter '-admin$' --include-terminated

RDS inventory

Lists DB instances across accounts (aws rds describe-db-instances, cross-account). Aurora members show up as instances; cluster_identifier links them to a cluster.

infra aws rds list
infra aws rds list --profile my-org-admin --region us-east-1 --excel --csv ./out/rds.csv

ElastiCache inventory

Lists Redis/Valkey replication groups across accounts (aws elasticache describe-replication-groups, cross-account). One SSO profile is used per account (names containing admin are preferred). Region comes from the profile unless --region is set.

# All SSO accounts, CSV in the current directory
infra aws elasticache list

# Single profile / region, plus Excel and JSON
infra aws elasticache list --profile my-org-admin --region us-east-1 --excel --json redis.json

# Admin profiles only, including standalone cache clusters
infra aws elasticache list --profile-filter '-admin$' --include-stale-cache --csv ./out/redis.csv

CSV extra columns application, owner_team, and notes are left empty for teams to fill in. Override with --extra-columns or pass an empty string to disable them.

SSM password audit

Scores SSM SecureString parameters with zxcvbn (aws ssm get-parameter --with-decryption, cross-account). Plaintext is never written to disk; ARNs, account IDs, and password-like tag keys are redacted in the CSV. Parameters tagged (or named) as prod are skipped unless you clear --skip-envs.

infra aws ssm audit
infra aws ssm audit --only-weak --out /tmp/ssm.csv
infra aws ssm audit --skip-envs '' --region us-east-1,us-west-2
infra aws ssm audit --account-names ./account-names.json

--account-names is an optional JSON object of {"123456789012": "shared-services"}. Without it, IAM account aliases are used when the caller can list them.

SSM name search

Look up Parameter Store names in one account (ssm describe-parameters). Values are not read or decrypted. Pass --profile for the target account (or reuse the last infra aws select). Exit status is 0 if any name matches, 1 if none do.

infra aws ssm search redis --profile my-org-admin
infra aws ssm search /stg/app --profile my-org-admin -r us-east-1
infra aws ssm search my-param --exact --format json
infra aws ssm search password --type SecureString --profile my-org-admin

👩‍💻 Development

We welcome contributions! To set up your local development environment:

1. Clone the repo: git clone https://github.com/hanyouqing/infra-cli.git
2. Install dev dependencies: make dev-install
3. Run linting: make lint
4. Run tests: make test

For more details, see CONTRIBUTING.md.

👤 Author & Contact

Youqing Han — maintainer of infra-cli.

Use Issues for bugs and feature requests. Email is fine for private contact, Code of Conduct reports, or partnership / speaking inquiries.

📜 License

This project is licensed under the Apache-2.0 License. See the LICENSE file for details.

Copyright © 2026 Youqing Han.