runbooks finops¶
Track | 48 commands | Cost Management. Auto-generated from Click registry on 2026-06-26.
QA/QC: 0/48 commands PASSED (v1.3.17)
L1 --help: 0/48 | L2 params: PASS | L4 cross-validation: PASS 100%
First time? Set up your AWS profiles
Before running any command, configure your AWS SSO profiles. See the Single Account or Multi-Account Landing Zone tabs below for copy-paste setup blocks.
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-profile |
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) |
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
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-profile --region $AWS_REGION
runbooks finops dashboard --all-profile --format table
Org-Wide Profile Routing — 4-Step Methodology¶
Each AWS profile has exactly one correct purpose. Mixing them returns empty results, not errors
(CROSS_ACCOUNT_SILENT_ZERO anti-pattern).
Authoritative standard (DISC-001): .claude/skills/aws/org-wide-resource-discovery.md — canonical 4-step methodology with P-ENRICH ranking and Config aggregator vs Resource Explorer priority. See also: aws-profile-semantics.md.
| Step | Name | Profile Env Var | Flag | API / Service | What-If Wrong |
|---|---|---|---|---|---|
| 1. DISCOVER | Org-wide resource inventory | $AWS_OPERATIONS_PROFILE |
--all-profile |
P1 (authoritative, un-capped): AWS Config aggregator (runbooks inventory resource-explorer default backend) — all accounts, paginated, no 1,000-result ceiling. P3 (cross-check only): Resource Explorer Search API — capped at 1,000 results per query; treat any count of exactly 1,000 as suspect. |
Wrong profile → aggregator index not found → silent-zero count |
| 2. ENUMERATE | Account names & IDs | $AWS_MANAGEMENT_PROFILE |
--all-profile |
AWS Organizations ListAccounts |
Wrong profile → empty account list → can't resolve resource owners |
| 3. ENRICH | Per-account attributes | Per-workload ~/.aws/config profile |
--profile |
Single-account describe-* / get-* (encryption, lifecycle, tags — aggregator can't return these) |
Skip this step → counts + cost present but target columns NULL |
| 4. COST | Cost attribution | $AWS_BILLING_PROFILE |
--all-profile |
Cost Explorer GetCostAndUsage |
Wrong profile → no CE access → cost columns blank or AccessDenied |
When to use --profile vs --all-profile
--all-profile $AWS_<PURPOSE>_PROFILE— Landing Zone-wide (hub accounts: Operations, Management, Billing). Always use the matching env var; never pass an LZ-wide profile with--profile.--profile $AWS_PROFILE— Single workload account only (Steps 3 + per-workload incident investigation).
Using --profile with an LZ-wide profile env var (e.g. --profile $AWS_BILLING_PROFILE) is a routing bug — the LZ hub account has no workload resources, so results are silently empty.
--all-profile flag behaviour differs by command group
--all-profile is value-taking (accepts a profile string) for finops, inventory, cfat, vpc, csdm, and workspaces command groups. For runbooks security, --all-profile is a boolean flag (bare, no value). Always use runbooks security baseline --all-profile (no value); never --all-profile $AWS_OPERATIONS_PROFILE for security commands.
# Step 1 — DISCOVER org-wide (Config aggregator, un-capped, P1 authoritative)
runbooks inventory resource-explorer --all-profile $AWS_OPERATIONS_PROFILE
# Step 2 — ENUMERATE accounts (Organizations API)
runbooks inventory discover --all-profile $AWS_MANAGEMENT_PROFILE
# Step 3 — ENRICH per-account (loop each workload profile from ~/.aws/config)
# Resolve account_id -> profile_name via runbooks.common.resolve_readonly_profile() (RB-3):
# from runbooks.common import resolve_readonly_profile
# profile = resolve_readonly_profile(account_id) # canonical account_id->profile resolver
runbooks security scan --profile $AWS_PROFILE # one call per workload account
# Step 4 — COST (Cost Explorer, org-wide consolidated billing)
runbooks finops dashboard --all-profile $AWS_BILLING_PROFILE
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) |
Commands¶
| Command | Description | Params | API Type |
|---|---|---|---|
analyze-ec2 |
EC2 cost analysis with 4-way enrichment. | 13 | read-only |
analyze-graviton-eligibility |
Graviton migration eligibility analysis for ARM64 cost optimization. | 9 | read-only |
analyze-s3-storage-lens |
Analyze S3 Storage Lens metrics for cost optimization. | 5 | read-only |
analyze-workspaces |
WorkSpaces cost analysis with decommission tier scoring. | 12 | read-only |
appstream-decommission-analysis |
AppStream decommission analysis with A1-A7 scoring framework. | 6 | read-only |
azure |
Azure Cost Management analysis. | 0 | read-only |
azure anomaly |
Detect cost anomalies (spending spikes). | 3 | read-only |
azure daily |
Daily cost breakdown by Azure service. | 4 | read-only |
azure dashboard |
Generate an HTML FinOps dashboard for Azure cost visibility. | 5 | read-only |
azure monthly |
Monthly cost summary with subscription breakdown. | 9 | read-only |
azure preflight |
Pre-flight auth and access validation for Azure FinOps. | 1 | read-only |
azure validate |
Validate SDK against Azure native API (ground truth). | 3 | read-only |
check-config-compliance |
Check AWS Config compliance and map to cost impact. | 6 | read-only |
cost-drops |
Detect month-over-month cost drops across all linked accounts and services. | 18 | read-only |
dashboard |
Multi-account AWS cost dashboard with persona-mode rendering and MCP validation. | 37 | read-only |
detect-orphans |
Detect orphaned AWS resources across multiple types. | 8 | read-only |
detect-rds-idle |
Detect idle RDS instances using CloudWatch metrics and produce a scored decommission candidate list. | 10 | read-only |
ebs |
EBS Volume Optimizer - Enterprise Multi-Region Storage Analysis | 6 | read-only |
ec2-decommission-analysis |
EC2 decommission analysis with E1-E7 scoring framework. | 7 | read-only |
ec2-snapshots |
EC2 snapshot cost optimization and cleanup analysis. | 8 | read-only |
enrich-workspaces |
Enrich a WorkSpaces inventory file with AWS Organizations account metadata. | 5 | read-only |
export |
Export financial analysis results in multiple formats. | 7 | read-only |
focus |
Enterprise Service Intelligence — tag governance, showback, CMDB and Backstage seeds. | 0 | read-only |
focus backstage-seed |
Generate Backstage catalog-info seed from service taxonomy. | 2 | read-only |
focus cmdb-seed |
Generate CMDB/CSDM CI and relationship seed files. | 3 | read-only |
focus showback |
Create service-owner showback from FOCUS-like cost data. | 2 | read-only |
focus validate-tags |
Validate cloud resource tags against mandatory enterprise schema. | 3 | read-only |
focus-validate |
Validate a FOCUS 1.2 CSV against the FinOps Foundation specification. | 3 | read-only |
infrastructure |
Infrastructure Optimization - analyze cost-savings opportunities across your account | 0 | read-only |
infrastructure analyze |
Comprehensive Infrastructure Optimization Analysis | 4 | read-only |
infrastructure elastic-ip |
Elastic IP optimization analysis (infrastructure cost-savings opportunity) | 1 | read-only |
infrastructure load-balancer |
Load Balancer optimization analysis (infrastructure cost-savings opportunity) | 1 | read-only |
infrastructure nat-gateway |
NAT Gateway optimization analysis (infrastructure cost-savings opportunity) | 1 | read-only |
infrastructure vpc-endpoint |
VPC Endpoint optimization analysis (infrastructure cost-savings opportunity) | 1 | read-only |
lambda-analysis |
Lambda cost and activity analysis with optimization signals. | 9 | read-only |
optimize |
Generate cost optimization recommendations for specific resource types. | 5 | read-only |
optimize-cloudwatch-costs |
Analyze and optimize CloudWatch log retention costs. | 10 | read-only |
optimize-s3-lifecycle |
S3 Lifecycle Optimizer - Automated Storage Cost Optimization | 7 | read-only |
optimize-savings-plans |
Generate hybrid Savings Plans + RI recommendations (60/30/10 strategy). | 9 | read-only |
s3-crossvalidate |
3-way S3 cross-validation: CLI (Config aggregator) vs boto3 (list-buckets) vs Storage Lens MCP. | 9 | read-only |
s3-noncurrent-sizing |
Measure noncurrent-version bytes for S3 buckets via live boto3 paginator. | 8 | read-only |
s3-storage-class-recommend |
READONLY S3 storage-class recommender across all org accounts. | 10 | read-only |
scenario |
Execute a FinOps business scenario analysis. | 6 | read-only |
sprint1 |
Run Sprint 1 cost optimization analysis. | 6 | read-only |
validate |
4-Way Validation: HTML vs CSV vs MCP vs AWS API | 8 | read-only |
validate-with-mcp |
Validate runbooks cost projections against MCP Cost Explorer (Feature 1). | 5 | read-only |
vizro |
Launch interactive Vizro FinOps dashboard (port 8050). | 4 | read-only |
workspaces-decommission-analysis |
WorkSpaces decommission analysis with W1-W6 scoring framework. | 5 | read-only |
Quick Start by Role¶
Cost optimization and financial operations across AWS accounts.
| Task | Command |
|---|---|
| Monthly cost report | runbooks finops dashboard --profile $AWS_BILLING_PROFILE |
| Cost trends | runbooks finops cost-trends --profile $AWS_BILLING_PROFILE --period monthly |
| Task | Command |
|---|---|
| EC2 right-sizing | runbooks finops analyze-ec2 --profile $AWS_PROFILE --output /tmp/ec2-analysis.json |
| Savings plan analysis | runbooks finops optimize-savings-plans --profile $AWS_BILLING_PROFILE |
| Idle RDS detection | runbooks finops detect-rds-idle --profile $AWS_PROFILE |
| Task | Command |
|---|---|
| Cost anomaly check | runbooks finops cost-drops --profile $AWS_BILLING_PROFILE --threshold 20 |
| Resource waste scan | runbooks finops optimize --profile $AWS_PROFILE --savings-target 0.2 |
Command Details¶
runbooks finops analyze-ec2¶
EC2 cost analysis with 4-way enrichment.
All Parameters (13)
| Parameter | Type | Default | Description |
|---|---|---|---|
--input/-i |
PATH | - | Input EC2 inventory Excel file (with Identifier, AWS Account, Region columns) |
--output/-o |
PATH | - | Output enriched Excel file (multi-sheet with cost analysis) |
--enable-organizations |
BOOL | True |
Enable Organizations metadata enrichment (default: enabled) |
--enable-cost |
BOOL | True |
Enable Cost Explorer enrichment (default: enabled) |
--enable-activity |
BOOL | False |
Enable CloudTrail activity tracking (default: disabled, takes 60-90 seconds) |
--include-12month-cost |
BOOL | True |
Include 12-month cost breakdown (default: enabled) |
--decommission-mode |
BOOL | False |
Decommission mode: Filter to 45 decision-focused columns (default: disabled, shows all 87 columns) |
--verbose/-v |
BOOL | False |
Show detailed logs |
--format |
CHOICE(compact | table | json) |
--output-dir |
PATH | . |
Destination folder for cost reports — wrong path = exports silently overwrite each other or land in an unreviewed... |
--profile |
STRING | - | AWS profile (KISS: auto-resolves management/billing/ops from AWS_MANAGEMENT_PROFILE, AWS_BILLING_PROFILE env vars) |
--all-profile |
STRING | - | Multi-Account: management profile for Organizations + Cost Explorer across all accounts. |
--cross-validate |
BOOL | False |
Re-derive the primary result from a 2nd independent source and report agreement vs the >=99.5%% accuracy gate. |
runbooks finops analyze-graviton-eligibility¶
Graviton migration eligibility analysis for ARM64 cost optimization.
All Parameters (9)
| Parameter | Type | Default | Description |
|---|---|---|---|
--input/-i |
PATH | - | Input EC2 enriched Excel file (output from analyze-ec2) |
--output/-o |
PATH | - | Output Excel file with Graviton eligibility assessment |
--all-profile |
STRING | - | Multi-account profile (defaults to $AWS_MANAGEMENT_PROFILE). |
--management-profile/-m |
STRING | - | AWS management profile for EC2 operations (defaults to service routing) |
--billing-profile/-b |
STRING | - | AWS billing profile for Cost Explorer (defaults to service routing) |
--enable-ami-check |
BOOL | True |
Enable AMI architecture compatibility checking (default: enabled) |
--enable-compute-optimizer |
BOOL | True |
Enable Compute Optimizer integration for confidence scoring (default: enabled) |
--verbose/-v |
BOOL | False |
Enable verbose logging |
--cross-validate |
BOOL | False |
Re-derive the primary result from a 2nd independent source and report agreement vs the >=99.5%% accuracy gate. |
runbooks finops analyze-s3-storage-lens¶
Analyze S3 Storage Lens metrics for cost optimization.
| Parameter | Type | Default | Description |
|---|---|---|---|
--profile |
STRING | - | AWS profile for single-account operations. |
--region |
STRING | ap-southeast-2 |
AWS region override (default: ap-southeast-2) |
--dry-run |
BOOL | True |
Safe analysis mode - no resource modifications (enterprise default) |
--region |
STRING | ap-southeast-2 |
AWS region for S3 client (S3 is global) |
--cross-validate |
BOOL | False |
Re-derive the primary result from a 2nd independent source and report agreement vs the >=99.5%% accuracy gate. |
runbooks finops analyze-workspaces¶
WorkSpaces cost analysis with decommission tier scoring.
All Parameters (12)
| Parameter | Type | Default | Description |
|---|---|---|---|
--input/-i |
PATH | - | Input WorkSpaces inventory Excel file (with Identifier, AWS Account, Region columns) |
--output/-o |
PATH | - | Output enriched Excel file (multi-sheet with cost analysis) |
--enable-organizations |
BOOL | True |
Enable Organizations metadata enrichment (default: enabled) |
--enable-cost |
BOOL | True |
Enable Cost Explorer enrichment (default: enabled) |
--enable-activity |
BOOL | False |
Enable CloudTrail activity tracking (default: disabled, takes 60-90 seconds) |
--include-12month-cost |
BOOL | True |
Include 12-month cost breakdown (default: enabled) |
--verbose/-v |
BOOL | False |
Show detailed logs |
--format |
CHOICE(compact | table | json) |
--output-dir |
PATH | . |
Destination folder for cost reports — wrong path = exports silently overwrite each other or land in an unreviewed... |
--profile |
STRING | - | AWS profile (KISS: auto-resolves management/billing/ops from AWS_MANAGEMENT_PROFILE, AWS_BILLING_PROFILE env vars) |
--all-profile |
STRING | - | Multi-Account: management profile for Organizations + Cost Explorer across all accounts. |
--cross-validate |
BOOL | False |
Re-derive the primary result from a 2nd independent source and report agreement vs the >=99.5%% accuracy gate. |
runbooks finops appstream-decommission-analysis¶
AppStream decommission analysis with A1-A7 scoring framework.
All Parameters (6)
| Parameter | Type | Default | Description |
|---|---|---|---|
--input/-i |
PATH | /tmp/appstream_discovery.csv |
Input AppStream inventory CSV file (default: /tmp/appstream_discovery.csv) |
--output/-o |
PATH | - | Output enriched Excel file with decommission analysis |
--enrich |
CHOICE(organizations | cost | activity |
--profile |
STRING | - | AWS profile (KISS: auto-resolves management/billing/ops from AWS_MANAGEMENT_PROFILE, AWS_BILLING_PROFILE env vars) |
--all-profile |
STRING | - | Multi-Account: management profile for Organizations + Cost Explorer across all accounts. |
--output-dir |
PATH | . |
Destination folder for cost reports — wrong path = exports silently overwrite each other or land in an unreviewed... |
runbooks finops azure¶
Azure Cost Management analysis.
runbooks finops azure anomaly¶
Detect cost anomalies (spending spikes).
| Parameter | Type | Default | Description |
|---|---|---|---|
--subscription/-s |
STRING | - | Azure subscription ID (uses default if not provided) |
--threshold/-t |
FLOAT | - | Anomaly threshold (e.g., 0.2 = 20% above rolling average) |
--days/-d |
INT | - | Rolling average period in days (default: 7) |
runbooks finops azure daily¶
Daily cost breakdown by Azure service.
| Parameter | Type | Default | Description |
|---|---|---|---|
--subscription/-s |
STRING | - | Azure subscription ID (uses default if not provided) |
--days/-d |
INT | - | Number of days to analyze (default: 7) |
--top-n/-n |
INT | - | Number of top services to display (default: 10) |
--export/-e |
CHOICE(json | csv) | - |
runbooks finops azure dashboard¶
Generate an HTML FinOps dashboard for Azure cost visibility.
| Parameter | Type | Default | Description |
|---|---|---|---|
--month/-m |
STRING | - | Billing period label, e.g. |
--budget |
FLOAT | - | Monthly budget in NZD (overrides AZURE_MONTHLY_BUDGET_NZD env var) |
--subscriptions-csv |
PATH | - | Path to Portal CSV export grouped by subscription (optional) |
--services-csv |
PATH | - | Path to Portal CSV export grouped by service name (optional) |
--output/-o |
PATH | - | Output HTML path (default: tmp/cloud-infrastructure/finops/azure/dashboard-{month}.html) |
runbooks finops azure monthly¶
Monthly cost summary with subscription breakdown.
All Parameters (9)
| Parameter | Type | Default | Description |
|---|---|---|---|
--subscription/-s |
STRING | - | Azure subscription ID (uses default if not provided) |
--months/-m |
INT | - | Number of months to analyze (default: 1, current MTD) |
--all-subscriptions/-a |
BOOL | - | Include all enabled subscriptions |
--start-date |
DATETIME | - | Start date for custom range (YYYY-MM-DD, e.g., 2025-11-01) |
--end-date |
DATETIME | - | End date for custom range (YYYY-MM-DD, e.g., 2025-11-30) |
--export/-e |
CHOICE(json | csv | xlsx) |
--mode |
CHOICE(cfo | cto | technical) |
--budget |
FLOAT | - | Monthly budget in NZD (overrides AZURE_MONTHLY_BUDGET_NZD env var) |
--granularity |
CHOICE(None | Daily | Monthly) |
runbooks finops azure preflight¶
Pre-flight auth and access validation for Azure FinOps.
| Parameter | Type | Default | Description |
|---|---|---|---|
--subscription/-s |
STRING | - | Azure subscription ID (defaults to AZURE_SUBSCRIPTION_ID env) |
runbooks finops azure validate¶
Validate SDK against Azure native API (ground truth).
| Parameter | Type | Default | Description |
|---|---|---|---|
--subscription/-s |
STRING | - | Azure subscription ID (uses default if not provided) |
--ground-truth |
FLOAT | - | Expected total cost for validation (from Azure Portal/CLI) |
--tolerance |
FLOAT | - | Acceptable variance in dollars (default: 0.01) |
runbooks finops check-config-compliance¶
Check AWS Config compliance and map to cost impact.
All Parameters (6)
| Parameter | Type | Default | Description |
|---|---|---|---|
--profile |
STRING | - | AWS profile for single-account operations. |
--region |
STRING | ap-southeast-2 |
AWS region override (default: ap-southeast-2) |
--dry-run |
BOOL | True |
Safe analysis mode - no resource modifications (enterprise default) |
--regions |
STRING | - | AWS regions to analyze |
--config-rules |
CHOICE(ebs-inuse | eip-attached | cw-retention |
--cross-validate |
BOOL | False |
Re-derive the primary result from a 2nd independent source and report agreement vs the >=99.5%% accuracy gate. |
runbooks finops cost-drops¶
Detect month-over-month cost drops across all linked accounts and services.
All Parameters (18)
| Parameter | Type | Default | Description |
|---|---|---|---|
--profile |
STRING | - | AWS profile for single-account operations. |
--region |
STRING | ap-southeast-2 |
AWS region override (default: ap-southeast-2) |
--dry-run |
BOOL | True |
Safe analysis mode - no resource modifications (enterprise default) |
-f/--format/--output-format |
CHOICE(json | csv | table |
--output-dir |
PATH | ./ops_evidence |
Directory for generated files and evidence packages |
--all-outputs |
BOOL | False |
Generate all output formats (JSON, CSV, PDF, Markdown) - use with --output-dir |
--csv |
BOOL | False |
Export to CSV format (convenience flag, activates --all-outputs) |
--json |
BOOL | False |
Export to JSON format (convenience flag, activates --all-outputs) |
--markdown |
BOOL | False |
Export to Markdown format (convenience flag, activates --all-outputs) |
--export |
BOOL | False |
[DEPRECATED] Use --all-outputs instead |
--validate |
BOOL | False |
Enable MCP validation for enhanced accuracy (≥99.5% target) |
--confidence-threshold |
FLOAT | 99.5 |
Minimum confidence threshold for validation (default: 99.5%%) |
--top |
INT | 30 |
Number of top cost drops to display (default: 30) |
--months |
CHOICE(2 | 3 | 4 |
--min-previous |
FLOAT | 1.0 |
Minimum previous month cost in USD to consider (default: 1.0) |
--billing-profile |
STRING | - | AWS billing profile for Cost Explorer (default: same as --profile) |
--org-profile |
STRING | - | AWS management profile for Organizations account names (optional) |
--cross-validate |
BOOL | False |
Re-derive the primary result from a 2nd independent source and report agreement vs the >=99.5%% accuracy gate. |
runbooks finops dashboard¶
Multi-account AWS cost dashboard with persona-mode rendering and MCP validation.
All Parameters (37)
| Parameter | Type | Default | Description |
|---|---|---|---|
--profile/-p |
STRING | - | AWS profile name (default: from AWS_PROFILE env var) |
--all |
BOOL | False |
[Multi-Account Mode] Enable org-wide cost aggregation. |
--all-profile |
STRING | - | DEPRECATED: Use --all with AWS_MANAGEMENT_PROFILE env var instead. |
--billing-profile |
STRING | - | [Multi-Account Mode] Billing account profile for Cost Explorer LINKED_ACCOUNT dimension queries (optional, defaults to... |
--ops-profile |
STRING | - | [Multi-Account Mode] Centralized ops profile for CloudWatch/operational data (optional, defaults to... |
--timeframe |
CHOICE(daily | weekly | monthly |
--month/-m |
STRING | - | Specific month to analyze (YYYY-MM format, e.g., 2025-12). |
--previous-month |
BOOL | False |
Show last completed calendar month (finance convention). |
--services |
STRING | - | Specific AWS services to analyze |
--accounts |
STRING | - | Specific AWS accounts to analyze |
--mode |
CHOICE(executive | architect | sre |
--executive |
BOOL | False |
DEPRECATED: Use --mode executive |
--dry-run |
BOOL | False |
Execute in dry-run mode (default: False for real execution) |
--verbose/-v |
BOOL | False |
Enable verbose diagnostic logging |
--top-n |
INT | 10 |
Number of top services to display in table (1-50, default: 10) |
--sort-by |
CHOICE(current | previous | change) |
--cost-threshold |
FLOAT | 0.0 |
Minimum cost threshold for service display (e.g., 100.0 for $100+) |
--summary-mode |
CHOICE(table | tree | both |
--output-format |
CHOICE(both | table | tree) |
--activity-analysis |
BOOL | False |
Enable resource activity analysis with decommission recommendations (E1-E7, R1-R7, S1-S7 signals) |
--show-zero-cost |
BOOL | False |
Show services with zero cost in both current and previous months (default: hide) |
--show-empty |
BOOL | False |
Show all resource types including those with 0 resources (for troubleshooting) |
--show-all-services |
BOOL | False |
Show all canonical services in Activity Health Tree (dim stub when no enricher data) |
--show-expected |
BOOL | False |
DEPRECATED: use --show-all-services |
--activity-filter |
STRING | () |
Filter Activity Tree to specific services (repeatable; lowercase: s3, lambda, cloudwatch, config, ssm, guardduty, kms,... |
--full-names |
BOOL | False |
Use full AWS API service names instead of simplified names (default: simplified like 'S3', 'VPC') |
--persona |
CHOICE(CFO | CTO | CEO |
--screenshot |
BOOL | False |
Capture Playwright screenshot of dashboard HTML export (requires console recording) |
--validation-level |
CHOICE(basic | mcp | strict) |
--output-dir |
PATH | outputs/finops-exports |
Destination folder for cost reports (HTML, XLSX, Markdown, JSON, CSV) — wrong path = exports silently overwrite each... |
--evidence-path |
PATH | - | Write JSON manifest of CSV files emitted to this path (file or directory) |
--export |
CHOICE(csv | markdown | |
--output-file |
STRING | - | Output file path for HTML export (default: outputs/finops-exports/dashboard_TIMESTAMP.html) |
--cost-metric |
CHOICE(blended | unblended | amortized |
--filter |
STRING | - | Filter DSL: 'service:EC2,RDS' 'cost>100' 'account:123' (repeatable) |
--group-by-tag |
STRING | - | Cost allocation tag key for grouping (e.g., CostCenter, Environment, Team) |
--cross-validate |
BOOL | False |
Re-derive the primary result from a 2nd independent source and report agreement vs the >=99.5%% accuracy gate. |
runbooks finops detect-orphans¶
Detect orphaned AWS resources across multiple types.
All Parameters (8)
| Parameter | Type | Default | Description |
|---|---|---|---|
--profile |
STRING | - | AWS profile for single-account operations. |
--region |
STRING | ap-southeast-2 |
AWS region override (default: ap-southeast-2) |
--dry-run |
BOOL | True |
Safe analysis mode - no resource modifications (enterprise default) |
--regions |
STRING | - | AWS regions to analyze |
--resource-type |
CHOICE(all | ebs | eip |
--validate-with-config |
BOOL | False |
Validate orphans with AWS Config compliance rules |
--executive |
BOOL | False |
Executive summary format (business narrative, <5 min review) |
--cross-validate |
BOOL | False |
Re-derive the primary result from a 2nd independent source and report agreement vs the >=99.5%% accuracy gate. |
runbooks finops detect-rds-idle¶
Detect idle RDS instances using CloudWatch metrics and produce a scored decommission candidate list.
All Parameters (10)
| Parameter | Type | Default | Description |
|---|---|---|---|
--profile |
STRING | - | AWS profile for single-account operations. |
--region |
STRING | ap-southeast-2 |
AWS region override (default: ap-southeast-2) |
--dry-run |
BOOL | True |
Safe analysis mode - no resource modifications (enterprise default) |
--lookback-days |
INT | 7 |
Analysis period in days for CloudWatch metrics (default: 7) |
--connection-threshold |
INT | 10 |
Daily connection threshold for idle detection (default: 10) |
--cpu-threshold |
FLOAT | 5.0 |
CPU percentage threshold for idle detection (default: 5.0) |
--export-json |
BOOL | False |
Export results to JSON file |
--output-file |
PATH | - | Output file path for JSON export |
--output-dir |
PATH | . |
Destination folder for cost reports — wrong path = exports silently overwrite each other or land in an unreviewed... |
--cross-validate |
BOOL | False |
Re-derive the primary result from a 2nd independent source and report agreement vs the >=99.5%% accuracy gate. |
runbooks finops ebs¶
EBS Volume Optimizer - Enterprise Multi-Region Storage Analysis
All Parameters (6)
| Parameter | Type | Default | Description |
|---|---|---|---|
--profile/-p |
STRING | - | AWS profile name (default: from AWS_PROFILE env var) |
--regions |
STRING | - | AWS regions to analyze (space-separated) |
--dry-run |
BOOL | True |
Execute in dry-run mode (READ-ONLY analysis) |
-f/--format/--export-format |
CHOICE(json | csv | markdown) |
--output-file |
STRING | - | Output file path for results export |
--usage-threshold-days |
INT | 7 |
CloudWatch analysis period in days |
runbooks finops ec2-decommission-analysis¶
EC2 decommission analysis with E1-E7 scoring framework.
All Parameters (7)
| Parameter | Type | Default | Description |
|---|---|---|---|
--input/-i |
PATH | - | Input EC2 inventory Excel file (with instance_id, account_id, region columns) |
--output/-o |
PATH | - | Output enriched Excel file with decommission analysis |
--enable-expensive-signals |
BOOL | False |
Enable expensive signals (CloudTrail activity, SSM, Compute Optimizer) |
--output-dir |
PATH | . |
Destination folder for cost reports — wrong path = exports silently overwrite each other or land in an unreviewed... |
--profile |
STRING | - | AWS profile (KISS: auto-resolves management/billing/ops from AWS_MANAGEMENT_PROFILE, AWS_BILLING_PROFILE env vars) |
--all-profile |
STRING | - | Multi-Account: management profile for Organizations + Cost Explorer across all accounts. |
--input-sheet |
STRING | ec2 |
Sheet name to read from input Excel file (default: 'ec2'). |
runbooks finops ec2-snapshots¶
EC2 snapshot cost optimization and cleanup analysis.
All Parameters (8)
| Parameter | Type | Default | Description |
|---|---|---|---|
--older-than-days |
INT | 90 |
Minimum age in days for cleanup consideration (default: 90) |
--validate |
BOOL | True |
Enable MCP validation for ≥99.5% accuracy (default: enabled) |
--cleanup |
BOOL | False |
Enable cleanup recommendations (READ-ONLY analysis only) |
--export-results |
BOOL | False |
Export analysis results to JSON file |
--safety-checks |
BOOL | True |
Enable comprehensive safety validations (default: enabled) |
--all |
BOOL | False |
Use all available AWS profiles for multi-account snapshot analysis |
--output-dir |
PATH | . |
Destination folder for cost reports — wrong path = exports silently overwrite each other or land in an unreviewed... |
--cross-validate |
BOOL | False |
Re-derive the primary result from a 2nd independent source and report agreement vs the >=99.5%% accuracy gate. |
runbooks finops enrich-workspaces¶
Enrich a WorkSpaces inventory file with AWS Organizations account metadata.
| Parameter | Type | Default | Description |
|---|---|---|---|
--input/-i |
PATH | - | Input WorkSpaces data file (Excel/CSV with 'AWS Account' column) |
--output/-o |
PATH | - | Output enriched data file (Excel/CSV/JSON) |
--all-profile |
STRING | - | Multi-account profile (defaults to $AWS_MANAGEMENT_PROFILE). |
--management-profile/-m |
STRING | - | AWS management profile (Organizations access) |
--display-only |
BOOL | False |
Display Rich CLI output without file export |
runbooks finops export¶
Export financial analysis results in multiple formats.
All Parameters (7)
| Parameter | Type | Default | Description |
|---|---|---|---|
--format |
CHOICE(csv | json | |
--output-dir |
STRING | ./finops_reports |
Destination folder for cost reports — wrong path = exports silently overwrite each other or land in an unreviewed... |
--include-quarterly |
BOOL | False |
Include quarterly intelligence data |
--executive-summary |
BOOL | False |
Generate executive summary format |
--mcp-validate |
BOOL | False |
Enable MCP validation for ≥99.5% accuracy cross-validation |
--input |
PATH | - | Input JSON or CSV file to re-export in a different format |
--profile |
STRING | - | Connect to the correct AWS account — wrong account = incorrect cost attribution. |
runbooks finops focus¶
Enterprise Service Intelligence — tag governance, showback, CMDB and Backstage seeds.
runbooks finops focus backstage-seed¶
Generate Backstage catalog-info seed from service taxonomy.
| Parameter | Type | Default | Description |
|---|---|---|---|
--taxonomy |
STRING | - | Service taxonomy JSON file. |
--output |
STRING | - | Output YAML path for Backstage catalog seed. |
runbooks finops focus cmdb-seed¶
Generate CMDB/CSDM CI and relationship seed files.
| Parameter | Type | Default | Description |
|---|---|---|---|
--mapping |
STRING | - | Service-to-resource mapping CSV. |
--ci-output |
STRING | - | Output CSV path for CMDB CI seed. |
--rel-output |
STRING | - | Output CSV path for CMDB relationship seed. |
runbooks finops focus showback¶
Create service-owner showback from FOCUS-like cost data.
| Parameter | Type | Default | Description |
|---|---|---|---|
--focus-cost |
STRING | - | FOCUS-format cost CSV input. |
--output |
STRING | - | Output CSV path for showback report. |
runbooks finops focus validate-tags¶
Validate cloud resource tags against mandatory enterprise schema.
| Parameter | Type | Default | Description |
|---|---|---|---|
--resources |
STRING | - | CSV of cloud resources to validate. |
--tags |
STRING | - | JSON file defining required tag schema. |
--output |
STRING | - | Output CSV path for compliance report. |
runbooks finops focus-validate¶
Validate a FOCUS 1.2 CSV against the FinOps Foundation specification.
| Parameter | Type | Default | Description |
|---|---|---|---|
--file |
PATH | - | CSV file to validate against FOCUS 1.2 spec. |
--json |
BOOL | False |
Emit structured JSON result to stdout (for CI/evidence pipelines). |
--profile |
STRING | - | AWS profile (reserved for future CUR S3 integration — not used in CC-ESI-002). |
runbooks finops infrastructure¶
Infrastructure Optimization - analyze cost-savings opportunities across your account
runbooks finops infrastructure analyze¶
Comprehensive Infrastructure Optimization Analysis
| Parameter | Type | Default | Description |
|---|---|---|---|
--components |
CHOICE(nat-gateway | elastic-ip | load-balancer |
--export-format |
CHOICE(json | csv | markdown) |
--output-file |
STRING | - | Output file path for results export |
--mcp-validate |
BOOL | - | Enable MCP validation for ≥99.5% accuracy cross-validation |
runbooks finops infrastructure elastic-ip¶
Elastic IP optimization analysis (infrastructure cost-savings opportunity)
| Parameter | Type | Default | Description |
|---|---|---|---|
--profile |
STRING | - | AWS profile for single-account EC2 analysis (defaults to $AWS_PROFILE). |
runbooks finops infrastructure load-balancer¶
Load Balancer optimization analysis (infrastructure cost-savings opportunity)
| Parameter | Type | Default | Description |
|---|---|---|---|
--profile |
STRING | - | AWS profile for single-account ELB analysis (defaults to $AWS_PROFILE). |
runbooks finops infrastructure nat-gateway¶
NAT Gateway optimization analysis (infrastructure cost-savings opportunity)
| Parameter | Type | Default | Description |
|---|---|---|---|
--profile |
STRING | - | AWS profile for single-account EC2 analysis (defaults to $AWS_PROFILE). |
runbooks finops infrastructure vpc-endpoint¶
VPC Endpoint optimization analysis (infrastructure cost-savings opportunity)
| Parameter | Type | Default | Description |
|---|---|---|---|
--profile |
STRING | - | AWS profile for single-account EC2 analysis (defaults to $AWS_PROFILE). |
runbooks finops lambda-analysis¶
Lambda cost and activity analysis with optimization signals.
All Parameters (9)
| Parameter | Type | Default | Description |
|---|---|---|---|
--all-profile |
STRING | - | Multi-account profile (defaults to $AWS_MANAGEMENT_PROFILE). |
--output/-o |
PATH | tmp/runbooks/finops/lambda-analysis.xlsx |
Output enriched Excel file with Lambda analysis |
--regions/-r |
STRING | - | AWS regions to include in cost analysis — omitting regions with active workloads = missing spend in the report. |
--enable-organizations |
BOOL | True |
Enable Organizations metadata enrichment (default: enabled) |
--enable-cost |
BOOL | True |
Enable Cost Explorer enrichment (default: enabled) |
--verbose/-v |
BOOL | False |
Show detailed logs |
--format |
CHOICE(compact | table | json) |
--output-dir |
PATH | . |
Destination folder for cost reports — wrong path = exports silently overwrite each other or land in an unreviewed... |
--cross-validate |
BOOL | False |
Re-derive the primary result from a 2nd independent source and report agreement vs the >=99.5%% accuracy gate. |
runbooks finops optimize¶
Generate cost optimization recommendations for specific resource types.
| Parameter | Type | Default | Description |
|---|---|---|---|
--resource-type |
CHOICE(ec2 | s3 | rds |
--savings-target |
FLOAT_RANGE | 0.3 |
Target savings percentage (0.1-0.8) |
--analysis-depth |
CHOICE(basic | comprehensive | enterprise) |
--mcp-validate |
BOOL | False |
Enable MCP validation for ≥99.5% accuracy cross-validation |
--profile |
STRING | - | Connect to the correct AWS account — wrong account = incorrect cost attribution. |
runbooks finops optimize-cloudwatch-costs¶
Analyze and optimize CloudWatch log retention costs.
All Parameters (10)
| Parameter | Type | Default | Description |
|---|---|---|---|
--profile |
STRING | - | AWS profile for single-account operations. |
--region |
STRING | ap-southeast-2 |
AWS region override (default: ap-southeast-2) |
--dry-run |
BOOL | True |
Safe analysis mode - no resource modifications (enterprise default) |
--regions |
STRING | - | AWS regions to include in cost analysis — omitting regions with active workloads = missing spend in the report. |
--mcp-validation |
BOOL | False |
Enable MCP validation for cost projections |
--format/--export-format |
CHOICE(json | csv | markdown) |
--output-file |
PATH | - | Output file path for results export |
--output-dir |
PATH | . |
Destination folder for cost reports — wrong path = exports silently overwrite each other or land in an unreviewed... |
--executive |
BOOL | False |
Executive summary format (business narrative, <5 min review) |
--cross-validate |
BOOL | False |
Re-derive the primary result from a 2nd independent source and report agreement vs the >=99.5%% accuracy gate. |
runbooks finops optimize-s3-lifecycle¶
S3 Lifecycle Optimizer - Automated Storage Cost Optimization
All Parameters (7)
| Parameter | Type | Default | Description |
|---|---|---|---|
--profile/-p |
STRING | - | AWS profile name (default: from AWS_PROFILE env var) |
--regions |
STRING | - | AWS regions to include in cost analysis — omitting regions with active workloads = missing spend in the report. |
--dry-run |
BOOL | True |
Execute in dry-run mode (READ-ONLY analysis) |
-f/--format/--export-format |
CHOICE(json | csv) | json |
--output-file |
STRING | - | Output file path for results export |
--output-dir |
PATH | . |
Destination folder for cost reports — wrong path = exports silently overwrite each other or land in an unreviewed... |
--cross-validate |
BOOL | False |
Re-derive the primary result from a 2nd independent source and report agreement vs the >=99.5%% accuracy gate. |
runbooks finops optimize-savings-plans¶
Generate hybrid Savings Plans + RI recommendations (60/30/10 strategy).
All Parameters (9)
| Parameter | Type | Default | Description |
|---|---|---|---|
--lookback-days |
INT | 90 |
Usage history analysis period (default: 90 days, minimum: 30) |
--term-years |
CHOICE(1 | 3) | 1 |
--payment-option |
CHOICE(ALL_UPFRONT | PARTIAL_UPFRONT | NO_UPFRONT) |
--all-profile |
STRING | - | Multi-account profile (defaults to $AWS_BILLING_PROFILE). |
--profile |
STRING | - | AWS billing profile for Cost Explorer (ADR-006 §A3-FinOps; defaults to $AWS_BILLING_PROFILE). |
--validate-with-mcp |
BOOL | True |
Enable MCP validation (≥99.5% accuracy, default: enabled) |
--output |
PATH | - | Export recommendations to Excel |
--verbose |
BOOL | False |
Enable verbose logging |
--cross-validate |
BOOL | False |
Re-derive the primary result from a 2nd independent source and report agreement vs the >=99.5%% accuracy gate. |
runbooks finops s3-crossvalidate¶
3-way S3 cross-validation: CLI (Config aggregator) vs boto3 (list-buckets) vs Storage Lens MCP.
All Parameters (9)
| Parameter | Type | Default | Description |
|---|---|---|---|
--all-profile |
STRING | - | AWS Operations profile ($AWS_OPERATIONS_PROFILE) — used by leg-1 Config aggregator. |
--mgmt-profile |
STRING | - | AWS Management profile ($AWS_MANAGEMENT_PROFILE) — for org account name resolution. |
--billing-profile |
STRING | - | AWS Billing profile ($AWS_BILLING_PROFILE) — for Cost Explorer RESOURCE_ID query. |
--accounts |
STRING | - | Comma-separated AWS account IDs to include (default: all discoverable). |
--mcp-json |
PATH | - | Path to leg-2 Storage Lens MCP JSON produced by finops-engineer. |
--output-json |
PATH | - | Path for the four-way validation output JSON (default: tmp/command-center/cross-validation/s3-3way-2026-06-24.json). |
--region |
STRING | ap-southeast-2 |
Primary AWS region for CloudWatch metrics. |
--scope-id |
STRING | rb-s3-3way-2026-06-24 |
Cross-validation scope identifier for evidence JSON. |
--leg1-csv |
PATH | - | Path to an existing leg-1 CSV produced by s3-storage-class-recommend. |
runbooks finops s3-noncurrent-sizing¶
Measure noncurrent-version bytes for S3 buckets via live boto3 paginator.
All Parameters (8)
| Parameter | Type | Default | Description |
|---|---|---|---|
--profile |
STRING | - | AWS named profile (ReadOnlyAccess). |
--region |
STRING | - | AWS region for the S3 client. |
--bucket |
STRING | - | Bucket name(s) to measure. |
--control-bucket |
STRING | - | Name of a known reference bucket. |
--expected-gb |
FLOAT | - | Expected noncurrent_gb for the control bucket (centre of ±tolerance check). |
--expected-versions |
INT | - | Minimum expected total_version_count for the control bucket. |
--tolerance-pct |
FLOAT | 5.0 |
Tolerance percentage around --expected-gb for the control-gate check. |
--output-format |
CHOICE(table | json) | table |
runbooks finops s3-storage-class-recommend¶
READONLY S3 storage-class recommender across all org accounts.
All Parameters (10)
| Parameter | Type | Default | Description |
|---|---|---|---|
--all-profile |
STRING | - | AWS Operations profile ($AWS_OPERATIONS_PROFILE). |
--mgmt-profile |
STRING | - | AWS Management profile ($AWS_MANAGEMENT_PROFILE). |
--billing-profile |
STRING | - | AWS Billing profile ($AWS_BILLING_PROFILE). |
--region |
STRING | ap-southeast-2 |
Primary AWS region for Config aggregator query. |
--noncurrent-expiration-days |
INT_RANGE | 30 |
Days for NoncurrentVersionExpiration rule (safe range: 30-90). |
--output-csv |
PATH | - | Path for per-bucket recommendation CSV output. |
--output-dir |
PATH | - | Directory for persona reports (cfo / cto / cloudops markdown files). |
--account |
STRING | - | Restrict discovery and enrichment to this AWS account ID. |
--accounts |
STRING | - | Comma-separated list of AWS account IDs to restrict to. |
--max-workers |
INT_RANGE | 4 |
Thread-pool size for concurrent per-account P-ENRICH. |
runbooks finops scenario¶
Execute a FinOps business scenario analysis.
All Parameters (6)
| Parameter | Type | Default | Description |
|---|---|---|---|
--profile |
STRING | - | AWS profile for single-account operations. |
--region |
STRING | ap-southeast-2 |
AWS region override (default: ap-southeast-2) |
--dry-run |
BOOL | True |
Safe analysis mode - no resource modifications (enterprise default) |
--name/-n |
CHOICE(workspaces | rds-snapshots | backup-investigation |
--regions |
STRING | ['ap-southeast-2'] |
AWS regions to analyze |
--format/--export-format |
CHOICE(json | csv | markdown) |
runbooks finops sprint1¶
Run Sprint 1 cost optimization analysis.
All Parameters (6)
| Parameter | Type | Default | Description |
|---|---|---|---|
--profile |
STRING | - | AWS profile for single-account operations. |
--region |
STRING | ap-southeast-2 |
AWS region override (default: ap-southeast-2) |
--dry-run |
BOOL | True |
Safe analysis mode - no resource modifications (enterprise default) |
--nat-gateways |
BOOL | True |
Include NAT Gateway optimization |
--snapshots |
BOOL | True |
Include EC2 snapshot cleanup |
--elastic-ips |
BOOL | True |
Include Elastic IP optimization |
runbooks finops validate¶
4-Way Validation: HTML vs CSV vs MCP vs AWS API
All Parameters (8)
| Parameter | Type | Default | Description |
|---|---|---|---|
--html/-h |
STRING | - | HTML report file for validation |
--csv/-c |
STRING | - | CSV cost data file for validation |
--profile/-p |
STRING | - | AWS billing profile for Cost Explorer validation (default: $AWS_BILLING_PROFILE). |
--validation-level/-v |
CHOICE(basic | mcp | strict) |
--deep-dive-bucket/-b |
STRING | - | S3 bucket for deep-dive validation |
--output-format/-o |
CHOICE(json | table | yaml) |
--export-report/-e |
STRING | - | Export validation report to file |
--automated |
BOOL | False |
Run automated L1 CLI vs L2 boto3 cross-validation (no CSV/HTML required) |
runbooks finops validate-with-mcp¶
Validate runbooks cost projections against MCP Cost Explorer (Feature 1).
| Parameter | Type | Default | Description |
|---|---|---|---|
--input/-i |
STRING | - | Input Excel file with cost projections |
--resource-type/-t |
CHOICE(ec2 | workspaces | lambda |
--tolerance/-tol |
FLOAT | 0.05 |
Variance tolerance (default: 5%) |
--all-profile |
STRING | - | Multi-account profile (defaults to $AWS_BILLING_PROFILE). |
--profile |
STRING | - | AWS billing profile for Cost Explorer (ADR-006 §A3-FinOps; defaults to $AWS_BILLING_PROFILE). |
runbooks finops vizro¶
Launch interactive Vizro FinOps dashboard (port 8050).
| Parameter | Type | Default | Description |
|---|---|---|---|
--data-file |
PATH | - | Pre-exported JSON file |
--profile |
STRING | - | AWS billing profile for live data (falls back to $AWS_BILLING_PROFILE) |
--port |
INT | 8050 |
Dashboard server port |
--mode |
CHOICE(executive | architect | sre) |
runbooks finops workspaces-decommission-analysis¶
WorkSpaces decommission analysis with W1-W6 scoring framework.
| Parameter | Type | Default | Description |
|---|---|---|---|
--input/-i |
PATH | - | Input WorkSpaces inventory Excel file (with Identifier, AWS Account, Region columns) |
--output/-o |
PATH | - | Output enriched Excel file with decommission analysis |
--output-dir |
PATH | . |
Destination folder for cost reports — wrong path = exports silently overwrite each other or land in an unreviewed... |
--profile |
STRING | - | AWS profile (KISS: auto-resolves management/billing/ops from AWS_MANAGEMENT_PROFILE, AWS_BILLING_PROFILE env vars) |
--all-profile |
STRING | - | Multi-Account: management profile for Organizations + Cost Explorer across all accounts. |