CLI reference

Generated from the installed command tree, so it always matches the CLI. Every command also has --help.

spendlens init <path>

Create a starter finops.yaml[/] (or, with --ci, a scheduled GitLab/GitHub pipeline).

Option Description
--ci Write a scheduled CI pipeline instead: gitlab | github.
--force Overwrite an existing file.

spendlens doctor

Check steampipe, powerpipe, aws plugin, AWS identity and Cost Explorer access.

Option Description
--config, -c Policy file (default: ./finops.yaml).
--profile, -p AWS profile (default: current credentials).
--set, -s Override a parameter, e.g. --set sizing.ec2_cpu_low=10 (repeatable).
--offline Local checks only: no AWS (STS), Steampipe or Cost Explorer calls.

spendlens query <sql>

Run an ad-hoc read-only SQL query against Steampipe.

Option Description
--config, -c Policy file (default: ./finops.yaml).
--profile, -p AWS profile (default: current credentials).
--format, -f Output format.
--out, -o Write output to this file.
--limit Max rows.

spendlens params

List every tunable parameter, its effective value and where it came from.

Option Description
--config, -c Policy file (default: ./finops.yaml).
--set, -s Override a parameter, e.g. --set sizing.ec2_cpu_low=10 (repeatable).
--var Raw Powerpipe mod variable, e.g. --var my_threshold=5 (repeatable).
--filter Only keys containing this text.
--format, -f Output format.
--out, -o Write output to this file.

spendlens config

Show the effective configuration and the Powerpipe variables it produces.

Option Description
--config, -c Policy file (default: ./finops.yaml).
--set, -s Override a parameter, e.g. --set sizing.ec2_cpu_low=10 (repeatable).
--var Raw Powerpipe mod variable, e.g. --var my_threshold=5 (repeatable).

spendlens plugins

List loaded features/plugins and what they contribute.

spendlens anomalies

Detect daily cost spikes vs each group's trailing baseline (median + MAD robust z-score).

Option Description
--group-by, -g service | account | region | usage-type | tag:
--days Recent days to check (default: anomaly.detect_days).
--threshold Robust z-score (default: anomaly.threshold).
--drops Also report sudden decreases.
--fail-on-anomaly Exit 3 if any anomaly (CI).
--config, -c Policy file (default: ./finops.yaml).
--profile, -p AWS profile (default: current credentials).
--set, -s Override a parameter, e.g. --set sizing.ec2_cpu_low=10 (repeatable).
--source live = query AWS; last = latest saved run; demo = bundled sample data.
--format, -f Output format.
--out, -o Write output to this file.

spendlens forecast

Projected month-end spend vs budgets.monthly_total and every monthly AWS Budget.

Option Description
--fail-on-risk Exit 3 if any budget is forecast over its limit.
--config, -c Policy file (default: ./finops.yaml).
--profile, -p AWS profile (default: current credentials).
--set, -s Override a parameter, e.g. --set sizing.ec2_cpu_low=10 (repeatable).
--source live = query AWS; last = latest saved run; demo = bundled sample data.
--format, -f Output format.
--out, -o Write output to this file.

spendlens dashboard

Build a self-contained HTML dashboard from the latest saved runs (no AWS calls).

Option Description
--out, -o Output HTML file.
--config, -c Policy file (default: ./finops.yaml).
--source last = your history DB; demo = bundled sample DB.

spendlens ask <question>

Ask the FinOps assistant, e.g. spendlens ask "Why did EC2 cost go up last month?"

Option Description
--interactive, -i Keep asking follow-up questions.
--source History to answer from: last (yours) or demo.
--live Also allow read-only live AWS queries via Steampipe.
--show-tools Show every tool call and SQL used.
--max-steps Tool-call limit per question (llm.max_steps).
--json Machine-readable answer + audit trail.
--config, -c Policy file (default: ./finops.yaml).
--profile, -p AWS profile (default: current credentials).
--set, -s Override a parameter, e.g. --set sizing.ec2_cpu_low=10 (repeatable).

spendlens notify

Post a summary of the latest saved runs to Slack and/or Teams (no AWS calls).

Option Description
--slack Post to Slack (URL from $notifications.slack_webhook_env).
--teams Post to Teams (URL from $notifications.teams_webhook_env).
--dry-run Print the payload(s) instead of sending.
--only-if-changes Send only when something needs attention (flagged change, anomaly, forecast over budget, new alarms).
--link Report URL for the 'Open report' button.
--title Message title (default: dashboard.title).
--config, -c Policy file (default: ./finops.yaml).
--source last = your history DB; demo = bundled sample DB.

spendlens report

Run all checks, write /*.json, the savings summary and /report.html.

Option Description
--out, -o Directory for JSON outputs and report.html.
--only Run only these steps (repeatable).
--skip Skip these steps (repeatable).
--source live = query AWS; demo = replay bundled sample data.
--config, -c Policy file (default: ./finops.yaml).
--profile, -p AWS profile (default: current credentials).
--set, -s Override a parameter, e.g. --set sizing.ec2_cpu_low=10 (repeatable).
--step-timeout Seconds per step.

spendlens tags types

List the resource types checked (add more in features/tags_catalog.py).

Option Description
--format, -f Output format.
--out, -o Write output to this file.

spendlens rightsize controls

List the controls in this check, with their service and resource type.

Option Description
--format, -f Output format.
--out, -o Write output to this file.

spendlens waste controls

List the controls in this check, with their service and resource type.

Option Description
--format, -f Output format.
--out, -o Write output to this file.

spendlens cost diff

What changed between two periods, per service/account/region/tag.

Option Description
--from Base period: YYYY-MM or YYYY-MM..YYYY-MM.
--to Compare period: YYYY-MM or YYYY-MM..YYYY-MM.
--mtd This month to date vs the same days last month.
--group-by, -g service | account | region | usage-type | instance-type | operation | record-type | tag:
--metric unblended | net_unblended | amortized | net_amortized | blended (default: cost.metric)
--include-credits Keep credit/refund record types.
--show Rows to show: changed, flagged, increases, decreases, all.
--top Only the N largest changes.
--total, --no-total Append a TOTAL row.
--fail-on-flag Exit 3 if any change is flagged (CI).
--config, -c Policy file (default: ./finops.yaml).
--profile, -p AWS profile (default: current credentials).
--set, -s Override a parameter, e.g. --set sizing.ec2_cpu_low=10 (repeatable).
--source live = query AWS; last = latest saved run; demo = bundled sample data.
--format, -f Output format.
--out, -o Write output to this file.

spendlens cost trend

Monthly cost per group for the last N months, with the latest month-over-month change.

Option Description
--months, -n Full months to show (default: cost.trend_months).
--include-current Add the current month to date.
--group-by, -g service | account | region | usage-type | instance-type | operation | record-type | tag:
--metric unblended | net_unblended | amortized | net_amortized | blended (default: cost.metric)
--include-credits Keep credit/refund record types.
--top Largest N groups by total.
--config, -c Policy file (default: ./finops.yaml).
--profile, -p AWS profile (default: current credentials).
--set, -s Override a parameter, e.g. --set sizing.ec2_cpu_low=10 (repeatable).
--source live = query AWS; last = latest saved run; demo = bundled sample data.
--format, -f Output format.
--out, -o Write output to this file.

spendlens cost showback

Cost per tag value (team, cost centre ...), share of total, untagged spend and budget variance.

Option Description
--tag-key, -t Tag key(s) (default: cost.showback_tag_keys).
--month YYYY-MM or YYYY-MM..YYYY-MM (default: last full month).
--mtd Current month to date.
--metric unblended | net_unblended | amortized | net_amortized | blended (default: cost.metric)
--config, -c Policy file (default: ./finops.yaml).
--profile, -p AWS profile (default: current credentials).
--set, -s Override a parameter, e.g. --set sizing.ec2_cpu_low=10 (repeatable).
--source live = query AWS; last = latest saved run; demo = bundled sample data.
--format, -f Output format.
--out, -o Write output to this file.

spendlens cost resources

Which resources' cost rose or fell: the last N days vs the N days before.

Option Description
--days Window size, 1-7 (default: cost.resource_days).
--metric unblended | net_unblended | amortized | net_amortized | blended (default: cost.metric)
--top Largest N changes.
--config, -c Policy file (default: ./finops.yaml).
--profile, -p AWS profile (default: current credentials).
--set, -s Override a parameter, e.g. --set sizing.ec2_cpu_low=10 (repeatable).
--source live = query AWS; last = latest saved run; demo = bundled sample data.
--format, -f Output format.
--out, -o Write output to this file.

spendlens savings hub

AWS Cost Optimization Hub recommendations (rightsizing, Graviton, idle, commitments) with AWS's estimates.

Option Description
--action Filter action types, e.g. Rightsize, Stop, PurchaseSavingsPlans.
--min-saving Only recommendations saving at least this per month.
--config, -c Policy file (default: ./finops.yaml).
--profile, -p AWS profile (default: current credentials).
--set, -s Override a parameter, e.g. --set sizing.ec2_cpu_low=10 (repeatable).
--source live = query AWS; last = latest saved run; demo = bundled sample data.
--format, -f Output format.
--out, -o Write output to this file.

spendlens savings commitments

Savings Plan / RI coverage per service (last full month, amortized) and Savings Plans about to expire.

Option Description
--config, -c Policy file (default: ./finops.yaml).
--profile, -p AWS profile (default: current credentials).
--set, -s Override a parameter, e.g. --set sizing.ec2_cpu_low=10 (repeatable).
--source live = query AWS; last = latest saved run; demo = bundled sample data.
--format, -f Output format.
--out, -o Write output to this file.

spendlens savings summary

One de-duplicated view of every saving found by the latest rightsize, waste, hub and commitment runs.

Option Description
--by Group by: source | service | control | none.
--top With --by none: largest N items.
--config, -c Policy file (default: ./finops.yaml).
--source last = your history DB; demo = bundled sample DB.
--format, -f Output format.
--out, -o Write output to this file.

spendlens history list

List saved runs, newest first.

Option Description
--feature e.g. tags, rightsize.
--limit Max runs.
--config, -c Policy file (default: ./finops.yaml).
--source last = your history DB; demo = bundled sample DB.
--format, -f Output format.
--out, -o Write output to this file.

spendlens history diff

What changed between two runs: new alarms, resolved alarms, removed resources.

Option Description
--feature Feature to compare.
--from Older run id (default: previous run).
--to Newer run id (default: latest run).
--config, -c Policy file (default: ./finops.yaml).
--source last = your history DB; demo = bundled sample DB.
--format, -f Output format.
--out, -o Write output to this file.

spendlens history path

Print the history database path (useful for CI cache/S3 sync).

Option Description
--config, -c Policy file (default: ./finops.yaml).