Transactions Commands

The stategraph tx command group manages transactions in Stategraph. Transactions track infrastructure changes and provide audit trails.

Commands

For commands that take --tx, the transaction ID can also be supplied via the STATEGRAPH_TX_ID environment variable.

stategraph tx create

Create a new transaction.

stategraph tx create --tenant <tenant-id> [options]

Options

Example

stategraph tx create \
  --tenant 550e8400-e29b-41d4-a716-446655440000 \
  --tag pipeline=github-actions \
  --tag commit=abc123

Output (JSON):

{
  "id": "...",
  "created_at": "2024-01-15T10:30:00Z",
  "created_by": "7cc3cdab-c634-4b7b-9523-ef7fd7013d87",
  "state": "open",
  "params": {},
  "tags": {
    "pipeline": "github-actions",
    "commit": "abc123"
  }
}

The completed_at and completed_by fields appear only after the transaction is committed or aborted.

stategraph tx create-with-session

Create a transaction and generate an API key for it. Useful for CI/CD pipelines where you want to scope Terraform operations to a single transaction.

stategraph tx create-with-session --tenant <tenant-id> [options]

Options

Example

stategraph tx create-with-session \
  --tenant 550e8400-e29b-41d4-a716-446655440000 \
  --tag pipeline=terraform-ci

Output (API key):

eyJhbGciOiJIUzI1NiIs...

Use this API key for Terraform backend authentication:

export TF_HTTP_PASSWORD=$(stategraph tx create-with-session --tenant $TENANT_ID)
terraform apply

The returned API key can be used with:
- Direct API calls (as a Bearer token)
- The CLI (via STATEGRAPH_API_KEY)

stategraph tx list

List transactions for a tenant.

stategraph tx list --tenant <tenant-id>

Options

Example

stategraph tx list --tenant 550e8400-e29b-41d4-a716-446655440000

Output (JSON):

{
  "results": [
    {
      "id": "...",
      "created_at": "2024-01-15T10:30:00Z",
      "created_by": "7cc3cdab-c634-4b7b-9523-ef7fd7013d87",
      "completed_at": "2024-01-15T10:30:05Z",
      "completed_by": "7cc3cdab-c634-4b7b-9523-ef7fd7013d87",
      "state": "committed",
      "params": {},
      "tags": {
        "pipeline": "github-actions"
      }
    }
  ]
}

stategraph tx costs

Show the cost delta (current vs planned) for a pending transaction. Only transactions opened by stategraph tf plan or stategraph tf mtx have a cost preview; a transaction created by hand has none.

stategraph tx costs --tx <transaction-id>

Options

Example

stategraph tx costs --tx 550e8400-e29b-41d4-a716-446655440000

Output:

Costs:
  Totals:
    Monthly:  130.82 USD → 140.16 USD   (+9.34 USD)
    Hourly:   0.18 USD → 0.19 USD   (+0.01 USD)
    Resources: 12 → 13 (+1)
    Coverage: 100.0% (unchanged)
  Per state:
    networking: +9.34/mo  (resources +1)
      + aws_nat_gateway.main                                +9.34

This is the same Costs: block that stategraph tf plan prints inline. Use tx costs to re-check a plan whose preview was not ready yet, or to inspect a plan's cost impact later. See Plan-Time Cost for how to read the delta.

stategraph tx abort

Abort an active transaction.

stategraph tx abort --tx <transaction-id>

Options

Example

stategraph tx abort --tx 550e8400-e29b-41d4-a716-446655440000

stategraph tx logs list

List logs for a transaction.

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

Options

Example

stategraph tx logs list --tx 550e8400-e29b-41d4-a716-446655440000

Output (JSON):

{
  "results": [
    {
      "id": "...",
      "action": "state_set",
      "object_type": "instance",
      "created_at": "2024-01-15T10:30:00Z",
      "state_id": "...",
      "user_id": "...",
      "data": { ... }
    }
  ]
}

CI/CD Integration

These examples run terraform apply directly, which requires your configuration to use the
Stategraph Terraform HTTP backend. See
Using Stategraph as a Terraform HTTP backend
for the backend "http" block — TF_HTTP_PASSWORD below is that backend's password.

GitHub Actions Example

jobs:
  terraform:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Create transaction
        run: |
          TOKEN=$(docker run --rm \
            -e STATEGRAPH_API_BASE=${{ secrets.STATEGRAPH_URL }} \
            ghcr.io/stategraph/stategraph:<version> stategraph tx create-with-session \
            --tenant ${{ secrets.TENANT_ID }} \
            --tag pipeline=github-actions \
            --tag commit=${{ github.sha }})
          echo "TF_HTTP_PASSWORD=$TOKEN" >> $GITHUB_ENV

      - name: Terraform Apply
        run: terraform apply -auto-approve

GitLab CI Example

terraform:
  script:
    - export TF_HTTP_PASSWORD=$(stategraph tx create-with-session --tenant $TENANT_ID --tag pipeline=gitlab-ci)
    - terraform apply -auto-approve

Transaction States

Next Steps

• States - State management
• Timeline - View transactions in UI