Cost Commands

The stategraph cost command group manages cost intelligence. It has two halves: managing FOCUS billing sources — connections that ingest your actual cloud spend from AWS, GCP, or Azure — and read-only cost queries over your computed estimates and billed spend (state and tenant cost, attribution, history, and coverage gaps).

Billing sources are admin-only and managed per tenant. For the full ingestion workflow, including how to create the FOCUS export in each cloud provider, see Cloud Billing (FOCUS). The plan-time cost preview is a separate feature — see Cost Analysis and Plan-Time Cost.

Commands

Billing sources

Command Description
stategraph cost billing-source add Add a FOCUS billing source to a tenant
stategraph cost billing-source list List billing sources in a tenant
stategraph cost billing-source update Update a billing source (omitted fields are unchanged)
stategraph cost billing-source enable Resume scheduled sync for a source
stategraph cost billing-source disable Pause scheduled sync for a source
stategraph cost billing-source sync Trigger a sync of a source now
stategraph cost billing-source remove Remove a source and its loaded billing rows

All billing-source subcommands take --tenant (or STATEGRAPH_TENANT_ID). Apart from add and list, they take the source ID as a positional argument.

Cost query commands

Command Description
stategraph cost state Cost of a single state: totals, coverage, and per-resource breakdown
stategraph cost calculate Trigger a fresh cost calculation for a state (enqueues a recompute)
stategraph cost unsupported Coverage gaps for a state: resources the pricing engine cannot price
stategraph cost tenant Tenant cost rollup: totals, coverage, and per-state breakdown
stategraph cost attribution Attribution of actual (FOCUS) spend to managed resources, by provider
stategraph cost history Tenant cost over time, one point per day
stategraph cost tag-keys Tag keys available for cost attribution in a tenant
stategraph cost unmanaged Billed resources the tenant's states do not manage

stategraph cost billing-source add

Add a FOCUS billing source. Point --source-uri at the exported files (Parquet or CSV; globs allowed). Credentials resolve ambiently — instance role, workload identity, az login, or the standard provider environment variables — so no secrets are handed to Stategraph.

stategraph cost billing-source add \
  --tenant <tenant-id> \
  --provider aws \
  --source-uri "s3://my-bucket/focus/data/**/*.parquet"

Options

Option Required Description
--tenant Yes Tenant ID (UUID)
--provider Yes Cloud provider: aws, gcp, or azure
--source-uri Yes FOCUS export location, e.g. s3://bucket/prefix/data/**/*.parquet
--region No Bucket region (AWS). Omit to resolve ambiently.
--window-months No Trailing reload window in months (default: 2, current plus previous)
--disabled No Create the source disabled (no scheduled sync until enabled)

Source URI shapes per provider:

Provider --source-uri
AWS s3://bucket/prefix/<export>/data/**/*.parquet
GCP gs://bucket/prefix/**/*.parquet
Azure abfss://container@account.dfs.core.windows.net/path/**/*.parquet

Example

Output (JSON):

{
  "id": "2d5013c1-57c6-47d2-8e99-c988d6ecb1c8",
  "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
  "provider": "aws",
  "source_uri": "s3://my-bucket/focus/data/**/*.parquet",
  "region": "us-east-1",
  "window_months": 2,
  "enabled": true,
  "created_at": "2026-06-11T12:47:32Z",
  "updated_at": "2026-06-11T12:47:32Z"
}

stategraph cost billing-source list

List the billing sources in a tenant, including each source's sync health.

stategraph cost billing-source list --tenant <tenant-id>

Output (table):

id            provider  source_uri                            region     window_months  enabled  last_status  last_synced_at        last_row_count
------------  --------  ------------------------------------  ---------  -------------  -------  -----------  --------------------  --------------
2d5013c1-...  aws       s3://my-bucket/focus/data/**/*.par...  us-east-1  2              true     ok           2026-06-11T03:10:02Z  184022

last_status, last_synced_at, and last_row_count confirm syncs are landing. Pass --format json for the structured form.

stategraph cost billing-source update

Update a billing source. Omitted fields are unchanged.

stategraph cost billing-source update --tenant <tenant-id> [options] <source-id>

Options

Option Required Description
--tenant Yes Tenant ID (UUID)
--source-uri No New FOCUS export location
--region No New bucket region
--window-months No New trailing reload window in months
--enabled No Enable (true) or disable (false) the source

Example

stategraph cost billing-source update --tenant <tenant-id> --window-months 3 <source-id>

stategraph cost billing-source enable / disable

Pause or resume a source's scheduled sync. Both take the source ID as the positional argument and print the updated source as JSON.

stategraph cost billing-source disable --tenant <tenant-id> <source-id>
stategraph cost billing-source enable  --tenant <tenant-id> <source-id>

stategraph cost billing-source sync

Trigger a sync of a billing source now instead of waiting for the schedule.

stategraph cost billing-source sync --tenant <tenant-id> [--from <date>] <source-id>

Options

Option Required Description
--tenant Yes Tenant ID (UUID)
--from No Backfill from this date (YYYY-MM-DD) instead of the trailing window

Example

# Backfill the year to date
stategraph cost billing-source sync --tenant <tenant-id> --from 2026-01-01 <source-id>

stategraph cost billing-source remove

Remove a billing source and the billing rows it loaded. Prompts for confirmation; pass --auto-approve to skip the prompt in scripts.

stategraph cost billing-source remove --tenant <tenant-id> [--auto-approve] <source-id>

Output:

Billing source 2d5013c1-57c6-47d2-8e99-c988d6ecb1c8 deleted

Cost queries

Beyond billing sources, the cost group reads computed cost data. Every cost query takes --api-base (or STATEGRAPH_API_BASE), and all but calculate accept --format=table|json|simple (default table).

Tenant-scoped queries (attribution, history, tag-keys, tenant, unmanaged) take --tenant (or STATEGRAPH_TENANT_ID). State-scoped queries (state, calculate, unsupported) take --state (a UUID; required, with no env-var equivalent) and do not accept --tenant.

stategraph cost state

Price a single state: the latest snapshot's totals, coverage, and per-resource breakdown. See State & Resource Cost for the fields.

stategraph cost state --state <state-id>

Takes --state (required) and --format.

stategraph cost calculate

Enqueue a fresh cost recompute for a state. It returns a task and runs in the background; a new snapshot lands when it finishes. Takes --state only — it does not accept --format.

stategraph cost calculate --state <state-id>

stategraph cost unsupported

List a state's coverage gaps: resources the pricing engine cannot price. Takes --state (required) and --format.

stategraph cost unsupported --state <state-id>

stategraph cost tenant

Tenant cost rollup: totals, coverage, and a per-state breakdown. With --tag-key, it breaks the rollup down by that tag's values instead. Takes --tenant (required), --format, and --tag-key.

stategraph cost tenant --tenant <tenant-id> [--tag-key Team]

stategraph cost attribution

Attribute actual (FOCUS) billed spend to your managed resources, by provider. Requires a connected billing source. Takes --tenant (required) and --format.

stategraph cost attribution --tenant <tenant-id>

stategraph cost history

Tenant cost over time, one point per day, oldest first. Takes --tenant (required) and --format, plus the window and grouping options below.

Option Required Description
--from No History window start (ISO 8601). Defaults to 30 days ago
--to No History window end (ISO 8601). Defaults to now
--group-by No Group each point by provider, type, or tag (with --tag-key)
--tag-key No Tag key to break each point down by when --group-by tag 
stategraph cost history --tenant <tenant-id> --group-by provider

stategraph cost tag-keys

List the Terraform tag keys available for cost attribution in a tenant. Takes --tenant (required) and --format.

stategraph cost tag-keys --tenant <tenant-id>

stategraph cost unmanaged

List billed resources the tenant's states do not manage. Takes --tenant (required), --format, and --limit (the maximum number of entries to return).

stategraph cost unmanaged --tenant <tenant-id> [--limit 20]

Next Steps