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
| 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). |