Velocity

Velocity is Stategraph's parallel execution engine for Terraform and OpenTofu. It uses the dependency graph to identify independent subgraphs and execute them concurrently.

Velocity requires a paid tier. Request access to get started.

Getting Started

Prerequisites

Note: Stategraph does not support Terraform workspaces yet. Each state maps to a single workspace.

Step 1: Navigate to Your Root Module

All Velocity commands run from the root of the Terraform module you want to manage:

cd /path/to/your/terraform/module

Step 2: Import Existing State (or Create a New One)

If you have existing Terraform state, pull it down to a local file and import it into Stategraph:

# Pull your current state to a local file
terraform state pull > terraform.tfstate

# Import it into Stategraph
# The state name must not already exist — this command creates it
stategraph import tf \
  --tenant <tenant-id> \
  --name <state-name> \
  terraform.tfstate

Run stategraph import tf from the root module directory and pass the path to the state file.

If you're starting fresh (no existing state), create an empty state instead:

stategraph states create --tenant <tenant-id> --name <state-name>

Step 3: Plan and Apply

Once your state is set up, use Velocity to plan and apply changes:

# Plan changes
stategraph tf plan --tenant <tenant-id> --out plan.json

# Apply the plan
stategraph tf apply plan.json

You can set STATEGRAPH_TENANT_ID to avoid passing --tenant on every command:

export STATEGRAPH_TENANT_ID="<tenant-id>"
stategraph tf plan --out plan.json

Version Control stategraph.json

Velocity commands generate a stategraph.json file in your module directory. This file stores the state configuration for your module. Commit this file to version control so your team shares the same Stategraph state binding:

git add stategraph.json
git commit -m "Add Stategraph configuration"

Usage

Velocity is used through the stategraph tf commands, which replace terraform plan and terraform apply:

# Plan changes
stategraph tf plan --tenant <tenant-id> --out plan.json

# Apply a plan
stategraph tf apply plan.json

# Plan across multiple states in a single transaction
stategraph tf mtx --tenant <tenant-id> --out plan.json ./networking ./compute ./application

Configuration

By default, Velocity uses tofu (OpenTofu) as the execution binary. Set the TF_CMD environment variable to use a different binary.

Plan Options

Option Description
--tenant Tenant ID (required, or set STATEGRAPH_TENANT_ID)
--out Output file for the plan (required)
--state State ID (auto-discovered from stategraph.json if not set)
--var Set a variable (key=value, repeatable)
--var-file Path to variable file
--force Force a resource address into the plan, supports globs (e.g., data.*)
--detailed-exitcode Return detailed exit code
Environment Variable Description
STATEGRAPH_TENANT_ID Tenant ID (alternative to --tenant flag)
TF_CMD Path to Terraform/OpenTofu binary (default: tofu)

Key Concepts

Topic Description
Transactions Transaction lifecycle: create, preview, commit
Resource-Level Locking Conflict detection and concurrent transaction handling
Multi-State Operations Coordinating plan/apply across multiple Terraform states

Other CLI Commands

Lower-level transaction management is available via stategraph tx:

# Create a transaction manually
stategraph tx create --tenant <tenant-id>

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

# Abort a transaction
stategraph tx abort --tx <tx-id>

# View transaction logs
stategraph tx logs list --tx <tx-id>

See Transaction Commands for the full CLI reference and API Reference for the REST API.