Cost Commands

The stategraph cost command group manages cost intelligence. Today it covers billing sources — connections to FOCUS billing exports that ingest your actual cloud spend from AWS, GCP, or Azure.

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

Commands

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 subcommands take --tenant (or STATEGRAPH_TENANT_ID). Apart from add and list, they take the source ID as a positional argument.

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

Next Steps