Quickstart

This walks you from zero to querying your own infrastructure in about ten minutes: install the CLI, connect it to a server, import an existing Terraform state, and explore it. If the vocabulary here is unfamiliar, skim Core concepts first.

Before you start

You need two things:

A Stategraph server. Use the hosted service (nothing to run), or self-host one with Docker Compose, Kubernetes, or ECS.
An existing Terraform project with a state file (terraform.tfstate or a pulled remote state). Stategraph onboards your real infrastructure — you don't start from scratch.

Step 1 — Install the CLI

The fastest way on macOS or Linux is the install script:

curl -sSL https://get.stategraph.com/install.sh | sh

Or use Homebrew on macOS:

brew tap stategraph/stategraph
brew install stategraph

For APT (Debian/Ubuntu), a binary download, or Docker, see the CLI installation options. Verify the install:

stategraph --help

Step 2 — Connect to a server

Point the CLI at your server and authenticate with an API key. Create a key in the console under Settings → API Keys, then set three environment variables:

export STATEGRAPH_API_BASE="https://your-server.example.com"   # your hosted or self-hosted URL
export STATEGRAPH_API_KEY="<your-api-key>"                      # from Settings → API Keys
export STATEGRAPH_TENANT_ID="<your-tenant-id>"                  # shown in stategraph info

Confirm the connection:

stategraph info

key       value
--------  --------------------------------------------
User      Jane Doe (jane@example.com)
Server    2.3.9
Client    2.3.9
Tenants   1
  Tenant  Production (7e45a833-24db-4847-b3da-bbb6f699f201)

--- What you can do next ---
  stategraph sql schema                        # Discover queryable tables
  stategraph query "SELECT * FROM resources"   # Browse your infrastructure
  stategraph states list --tenant ID           # List Terraform states
  stategraph gaps --tenant ID --provider aws   # Find unmanaged resources
  stategraph blast-radius ADDR --state ID      # Check impact before changes

stategraph info is your orientation command — it shows who you are, which server and tenant you're talking to, and suggested next steps.

Step 3 — Import an existing state

From the directory that holds your Terraform configuration and its state file, import both into a new Stategraph state in one step:

stategraph import tf \
  --tenant "$STATEGRAPH_TENANT_ID" \
  --workspace default \
  --name my-app \
  terraform.tfstate

Stategraph first reminds you that it manages state independently of your existing Terraform backend — answer y to continue. It then creates a state, imports your state and HCL, and writes a stategraph.json in the directory so the CLI knows which state this configuration drives. Verify it landed:

stategraph states summary --state <state-id>

For the full onboarding flow — remote state, modules, and attached files — see Import.

Step 4 — Explore your infrastructure

List the states in your tenant:

stategraph states list

id                                    name             workspace  group_id                              created_at
------------------------------------  ---------------  ---------  ------------------------------------  --------------------
9cb4ba52-02a4-4c8a-84d8-9034a26af546  my-app           default    09a29aea-971a-4917-91e6-db5198dd793c  2026-06-27T00:00:00Z

Query your whole estate with SQL. Start by discovering the tables, then ask a question:

stategraph sql schema
stategraph query "SELECT type, count(*) AS n FROM resources GROUP BY type ORDER BY n DESC LIMIT 5"

type                 n
-------------------  ---
aws_iam_role         42
aws_instance         18
aws_security_group   15
aws_subnet           12
aws_s3_bucket        9

Check the blast radius of a resource — everything a change to it could affect — before you touch it:

stategraph blast-radius aws_subnet.public --state <state-id>

resource_address               address                        index  distance
-----------------------------  -----------------------------  -----  --------
aws_subnet.public              aws_subnet.public                     0
aws_instance.web               aws_instance.web[0]            0      1
aws_instance.web               aws_instance.web[1]            1      1
aws_route_table_association.a  aws_route_table_association.a         1

See what a state is costing you:

stategraph cost state --state <state-id>

address                 type                provider  region     monthly     hourly    supported     no_price
----------------------  ------------------  --------  ---------  ----------  --------  ------------  --------
(total)                                                          790.736000  1.083200  18/21 priced
aws_instance.analytics  aws_instance        aws       us-east-1  367.920000  0.504000  true          false
aws_instance.web[0]     aws_instance        aws       us-east-1  70.080000   0.096000  true          false
aws_security_group.app  aws_security_group  aws                                        true          true

Step 5 — Plan a change

With stategraph.json in place, Stategraph is a drop-in for the Terraform workflow. Edit your .tf files, then:

stategraph tf plan

This compares your configuration against the current state and shows the diff — no --out needed for a read-only preview. To apply, run stategraph tf apply (it can plan and apply in one step, or apply a saved plan file). Because Stategraph locks at the resource level, teammates changing unrelated resources can plan and apply at the same time.

See Velocity setup for wiring multiple workspaces and CI.

Next steps

Core concepts — the model behind what you just did
Velocity — parallel plan and apply with resource-level locking
Insights — blast radius, the graph explorer, and the transaction timeline
Inventory — query your estate with SQL and find unmanaged resources
Cost Analysis — per-state and per-tenant cost, attribution, and plan-time deltas