Setup

This guide shows you how to set up Velocity for parallel Terraform and OpenTofu execution.

Prerequisites

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

Step 1: Create an API Key

  1. Open Stategraph at http://localhost:8080
  2. Log in (via local authentication or OAuth)
  3. Navigate to Settings
  4. In the API Keys section, click Create API Key
  5. Copy the generated token and set it as an environment variable:
export STATEGRAPH_API_KEY="<your-api-key>"

Step 2: Configure the CLI

Point the CLI at your Stategraph server:

export STATEGRAPH_API_BASE="http://localhost:8080"

List your tenants to get your tenant ID:

stategraph user tenants list

Output:

550e8400-e29b-41d4-a716-446655440000    my-org

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

export STATEGRAPH_TENANT_ID="550e8400-e29b-41d4-a716-446655440000"

Step 3: 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 4: 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 5: 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

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)

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.