Transactions

A Velocity transaction captures a set of infrastructure changes and tracks them through plan and apply.

Lifecycle

Create → Preview (Plan) → Commit (Apply)

Transaction States

Create

stategraph tf plan creates a transaction automatically when it detects HCL changes. You can also create transactions manually:

stategraph tx create --tenant <tenant-id>

Preview (Plan)

stategraph tf plan --out plan.json

When a pricing service is configured, stategraph tf plan also prints a
cost delta for the change — current vs planned monthly cost — right under the diff.

Multiple previews can run concurrently against the same state. Each operates on an independent set of resources.

For multi-state plans across directories:

stategraph tf mtx --out plan.json ./networking ./compute

Commit (Apply)

stategraph tf apply plan.json

You can also commit without a saved plan file: stategraph tf apply with no plan argument runs a fresh plan, shows the diff, and prompts for approval before committing (like terraform apply). Pass --auto-approve to skip the prompt — with a non-tty stdin or --silent (STATEGRAPH_SILENT) the apply fails unless --auto-approve is also given:

stategraph tf apply --tenant <tenant-id> --auto-approve

Before applying, Stategraph runs a conflict check. If another transaction has committed changes to overlapping resources since this transaction was created, the commit is rejected with the conflicting transaction IDs. Re-run stategraph tf plan to pick up the new state and retry.

Abort

Cancel a transaction at any point before commit completes:

stategraph tx abort --tx <tx-id>

Inspect

# List transactions for a tenant
stategraph tx list --tenant <tenant-id>

# View logs for a specific transaction
stategraph tx logs list --tx <tx-id>

See Transaction Commands for the full CLI reference including options, output formats, and CI/CD integration examples.

API Reference

The CLI wraps these API endpoints. Use the API directly for custom integrations.