Skip to content

CloudOps-Runbooks CLI

Enterprise AWS automation toolkit with 122 commands across 8 groups, supporting both single-account and multi-account Landing Zone operations.

Installation

uv tool install runbooks

pip install runbooks

git clone https://github.com/nnthanh101/cloudops.git
cd cloudops
uv sync
uv run runbooks --help

Quick Verification

# Check installation
runbooks --version

# List all command groups
runbooks --help

AWS Profile Configuration

All runbooks commands support these common options for AWS authentication:

Option Scope When to Use
--profile PROFILE Single account Developer/operator targeting one AWS account
--all-profiles All accounts (Landing Zone) Platform team — discovers across all SSO profiles
--region REGION Override region Non-default region (default: ap-southeast-2)
--dry-run Safe mode Analysis only, no mutations (recommended for first run)
--output-dir DIR Output path Directory for generated reports (default: output/)
--format FORMAT Output format table, json, csv, markdown (varies by command)

Single Account Setup

Copy and configure:

# =============================================================
# AWS Single Account Configuration
# =============================================================
export AWS_REGION="ap-southeast-2"
export AWS_PROFILE="your-account-profile"

# Authenticate via SSO
aws sso login --profile $AWS_PROFILE

# Verify
aws sts get-caller-identity --profile $AWS_PROFILE

# Run any command
runbooks finops dashboard --profile $AWS_PROFILE

Multi-Account Landing Zone Setup

Copy and configure all 4 environment variables:

# =============================================================
# AWS Multi-Account Landing Zone Configuration
# =============================================================
export AWS_REGION="ap-southeast-2"

## Single account (default fallback)
export AWS_PROFILE="your-default-profile"

## FinOps/Billing profile (READ-ONLY access to Cost Explorer)
export AWS_BILLING_PROFILE="your-billing-readonly-profile"

## Management account profile (Organizations, Control Tower)
export AWS_MANAGEMENT_PROFILE="your-management-readonly-profile"

## Centralized Operations account profile (for shared resources)
export AWS_OPERATIONS_PROFILE="your-operations-readonly-profile"

# =============================================================
# Authenticate all profiles
# =============================================================
aws sso login --profile $AWS_BILLING_PROFILE
aws sso login --profile $AWS_MANAGEMENT_PROFILE
aws sso login --profile $AWS_OPERATIONS_PROFILE

# =============================================================
# Verify connectivity
# =============================================================
aws sts get-caller-identity --profile $AWS_BILLING_PROFILE
aws sts get-caller-identity --profile $AWS_MANAGEMENT_PROFILE

# =============================================================
# Run org-wide commands
# =============================================================
runbooks inventory collect --all-profiles --region $AWS_REGION
runbooks finops dashboard --all-profiles --format table

Environment Variables Reference

Variable Required Purpose
AWS_REGION Yes Target AWS region (default: ap-southeast-2)
AWS_PROFILE Yes Default profile when --profile is omitted
AWS_BILLING_PROFILE LZ only Cost Explorer data enrichment
AWS_MANAGEMENT_PROFILE LZ only Organizations metadata enrichment
AWS_OPERATIONS_PROFILE LZ only Centralized Operations shared resources
RUNBOOKS_TEST_MODE No Set to 1 for offline/mock mode (no AWS calls)

Command Groups

Group Commands Purpose API Type
cfat 5 Cloud Foundations Assessment Read-only
finops 35 Cost optimization and FinOps analytics Read-only
inventory 50 Multi-account resource discovery Read-only / Write
operate 9 EC2, S3, VPC, CloudFormation operations Write
remediation 4 Security remediation automation Write
security 5 Security assessment and baseline Read-only / Write
validation 7 Cross-validation and benchmarking Read-only
vpc 7 VPC analysis and VPCE cleanup Read-only / Write

Quick Start by Role

# Org-wide inventory discovery (67 accounts)
runbooks inventory collect --all-profiles

# Cost dashboard across all accounts
runbooks finops dashboard --all-profiles --format table

# Security baseline assessment
runbooks security baseline --all-profiles

# Monthly cost dashboard
runbooks finops dashboard --profile $AWS_BILLING_PROFILE

# Detect orphaned resources
runbooks finops detect-orphans --profile $AWS_BILLING_PROFILE

# Infrastructure optimization analysis
runbooks finops infrastructure analyze --profile $AWS_BILLING_PROFILE

# Single-account VPC topology
runbooks vpc topology --profile $AWS_PROFILE

# EC2 analysis
runbooks finops analyze-ec2 --profile $AWS_PROFILE

# CloudFormation stack operations
runbooks operate cloudformation deploy --profile $AWS_PROFILE

Full Reference

See All Commands for the complete command reference with parameter details.