States Commands

The stategraph states command group manages Terraform states in Stategraph.

Commands

stategraph states create

Create a new empty state.

stategraph states create --tenant <tenant-id> --name <state-name> [options]

Options

By default, states create writes a stategraph.json in the current directory that binds it to the
new state (the CLI uses this to resolve the state on later commands). Commit that file, or pass
--no-write-config to skip writing it.

Example

stategraph states create --tenant 550e8400-e29b-41d4-a716-446655440000 --name "networking"

Output (JSON):

{
  "id": "...",
  "name": "networking",
  "group_id": "...",
  "workspace": "default",
  "created_at": "2024-01-15T10:30:00Z"
}

stategraph states delete

Permanently delete a state and all of its related data (resources, instances, providers, outputs,
raw states, transaction logs, and check entries/results). This cannot be undone. By default the
command prompts for interactive confirmation before deleting.

stategraph states delete --state <state-id>

Options

Examples

Delete a state (prompts for confirmation):

stategraph states delete --state 550e8400-e29b-41d4-a716-446655440000

You are asked to confirm before the state is permanently removed.

Delete without prompting (e.g. in CI):

stategraph states delete --state 550e8400-e29b-41d4-a716-446655440000 --auto-approve

Notes

• Requires admin privileges.
• Deletion is permanent — there is no soft delete or undo.
• Returns an error if the state is not found or the user lacks permission.

stategraph states list

List all states for a tenant.

stategraph states list --tenant <tenant-id>

Options

Example

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

Output (JSON):

{
  "results": [
    {
      "created_at": "2024-01-15T10:30:00Z",
      "group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "id": "...",
      "name": "networking",
      "workspace": "production"
    }
  ]
}

Soft-deleted states include additional deleted_at and deleted_by fields.

stategraph states resolve

Resolve a state ID from a workspace or state name. Useful in scripts that need the state ID without hardcoding it.

stategraph states resolve [options]

Options

Examples

Resolve by workspace (using stategraph.json):

stategraph states resolve --workspace staging

Resolve by name:

stategraph states resolve --name networking

Get the group ID:

stategraph states resolve --group

stategraph states export

Export a Terraform state file.

stategraph states export [options]

Options

Example

stategraph states export --workspace production > terraform.tfstate

stategraph states import

Import an existing Terraform state file.

stategraph states import --tenant <tenant-id> --name <state-name> [options] <state-file>

Options

Example

# Import with tags
stategraph states import \
  --tenant 550e8400-e29b-41d4-a716-446655440000 \
  --name "networking" \
  --workspace "production" \
  --tag environment=prod \
  --tag team=platform \
  terraform.tfstate

stategraph states summary

Get summary statistics for a state.

stategraph states summary --state <state-id>

Options

Example

stategraph states summary --state 550e8400-e29b-41d4-a716-446655440000

Output (tab-separated):

Edges       234
Instances   150
Modules     8
Providers   3
Resources   45

stategraph states resources summary

Get instance counts by resource type.

stategraph states resources summary --state <state-id>

Options

Example

stategraph states resources summary --state 550e8400-e29b-41d4-a716-446655440000

Output (tab-separated):

aws_instance          20
aws_security_group    15
aws_subnet            6
aws_iam_role          12

stategraph states instances

Instance-related operations.

stategraph states instances blast-radius

Get the blast radius for a specific instance — all resources that depend on it or that it depends on. stategraph blast-radius is a top-level alias for the same command.

stategraph states instances blast-radius --state <state-id> <instance-address>

Options

Example

stategraph states instances blast-radius \
  --state 550e8400-e29b-41d4-a716-446655440000 \
  "aws_vpc.main"

Output (table):

resource_address        address                 index  distance
----------------------  ----------------------  -----  --------
aws_vpc.main            aws_vpc.main                   0
aws_instance.web        aws_instance.web               1
aws_security_group.web  aws_security_group.web         1
aws_subnet.public_a     aws_subnet.public_a            1
aws_subnet.public_b     aws_subnet.public_b            1

Columns: resource_address, address, distance

stategraph states instances query

Query instances with a tag filter. The filter uses key:value tag syntax (not SQL). Valid tag keys are address, resource_address, module, provider, type, and attr.

stategraph states instances query --state <state-id> [-i] <query>

Options

Example

stategraph states instances query \
  --state 550e8400-e29b-41d4-a716-446655440000 \
  "type:aws_instance"

stategraph states modules list

List modules in a state.

stategraph states modules list --state <state-id>

Options

Example

stategraph states modules list --state 550e8400-e29b-41d4-a716-446655440000

Output (tab-separated):

module.vpc           10    25
module.eks           8     45
module.rds           4     12

Columns: name, resource_count, instance_count

stategraph states anonymize

Anonymize a Terraform state JSON file locally — useful for sharing a state for debugging or support
without exposing real values. It reads a state file and prints an anonymized copy; it does not
contact the server.

stategraph states anonymize <state-file> [--seed <n>]

Options

Example

stategraph states anonymize terraform.tfstate --seed 42 > anonymized.tfstate

Scripting Examples

Export all states to JSON

stategraph states list --tenant $TENANT_ID --format json | jq -r '.results[] | .id' | while read state_id; do
  echo "Exporting $state_id..."
  stategraph states summary --state "$state_id"
done

Find states with specific resource types

stategraph states list --tenant $TENANT_ID --format json | jq -r '.results[] | .id' | while read state_id; do
  count=$(stategraph states resources summary --state "$state_id" 2>/dev/null | grep aws_rds_cluster | awk '{print $2}')
  if [ -n "$count" ] && [ "$count" -gt 0 ]; then
    echo "State $state_id has $count RDS clusters"
  fi
done

Next Steps

• Transactions - Manage transactions
• SQL - Query infrastructure