CLI

The stategraph CLI is the command-line client for Infrastructure as a Database. It works with states, transactions, SQL queries, cost, and security data, from the terminal, in scripts, and in automation. It runs on your machine or CI runner. The server does not run your plans and applies.

Stategraph Orchestration runs start from pull request commands, not from the CLI.

Installation

Install the binary with the install script, Homebrew, APT, or a download. The Docker image also works, but a container needs volume mounts and environment variables. The releases page lists the versions.

Install Script (macOS & Linux)

Install the latest version:

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

Homebrew (macOS)

brew tap stategraph/stategraph
brew install stategraph

To upgrade:

brew upgrade stategraph

APT (Debian & Ubuntu)

# Add the signing key
curl -fsSL https://stategraph.github.io/releases/apt/KEY.gpg \
  | sudo gpg --dearmor -o /etc/apt/keyrings/stategraph.gpg

# Add the repository
echo "deb [signed-by=/etc/apt/keyrings/stategraph.gpg] https://stategraph.github.io/releases/apt stable main" \
  | sudo tee /etc/apt/sources.list.d/stategraph.list

# Install
sudo apt update
sudo apt install stategraph

To upgrade:

sudo apt update
sudo apt upgrade stategraph

The APT packages are for amd64 and arm64. For RPM-based distributions, use the yum repository on Releases.

Binary Installation

Download the file for your platform from the releases page, then install it:

tar xzf stategraph-<platform>.tar.gz
sudo mv stategraph /usr/local/bin/

Check the installation:

stategraph --version
stategraph --help

With no arguments, stategraph shows a getting-started screen. --help shows all commands and aliases.

Docker

docker pull ghcr.io/stategraph/stategraph:<version>

Extract the binary from Docker

Without Homebrew or curl, copy the binary out of the image:

docker create --name sg-tmp ghcr.io/stategraph/stategraph:<version>
docker cp sg-tmp:/usr/local/bin/stategraph ./stategraph
docker rm sg-tmp
sudo mv stategraph /usr/local/bin/

Running the CLI via Docker

In CI pipelines or containers, mount your working directory and pass the environment variables:

docker run --rm \
  -e STATEGRAPH_API_BASE \
  -e STATEGRAPH_API_KEY \
  -v $(pwd):/workspace \
  -w /workspace \
  ghcr.io/stategraph/stategraph:<version> \
  states import --tenant <tenant-id> --name "networking" terraform.tfstate

Or create an alias:

alias stategraph='docker run --rm -e STATEGRAPH_API_BASE -e STATEGRAPH_API_KEY -v $(pwd):/workspace -w /workspace ghcr.io/stategraph/stategraph:<version>'

Configuration

API Base URL

Set the Stategraph server URL:

export STATEGRAPH_API_BASE=https://stategraph.example.com

Or give --api-base with each command, after the subcommand:

stategraph user whoami --api-base https://stategraph.example.com

Authentication

The CLI sends an access token as a Bearer token. Create one in the console under Settings, or with stategraph user access-tokens create, then export it:

export STATEGRAPH_API_KEY="<your-access-token>"
stategraph user tenants list

For what a token can do, see Access tokens and capabilities.

Command Structure

stategraph <command> <subcommand> [options]

Available Commands

Aliases

In a pull request comment, stategraph plan and stategraph apply are Orchestration commands.

Quick Examples

Orient yourself

stategraph info

In table or simple format, info also prints suggested next steps. Run it first, as a new user or as an AI agent.

Check current user

stategraph user whoami

List your tenants

stategraph user tenants list

List states in a tenant

stategraph states list --tenant <tenant-id>

Import a Terraform state file

Run it from the root of your Terraform module, with the --var-file and --var flags that you give to terraform plan:

stategraph import tf \
  --tenant <tenant-id> \
  --name "networking" \
  terraform.tfstate

To replace an existing state with new HCL and state data, add --overwrite:

stategraph import tf --overwrite \
  --tenant <tenant-id> \
  --name "networking" \
  terraform.tfstate

For a guided import, see Import your Terraform state. For the full workflow, with plan and apply, see Set up Infrastructure as a Database.

Run an SQL query

stategraph sql query "SELECT type, count(*) FROM resources GROUP BY type"

Get blast radius for a resource

stategraph states instances blast-radius --state <state-id> "aws_vpc.main"

Run gap analysis

stategraph tenant gaps analyze --tenant <tenant-id> --provider aws

Attach data files

When your HCL reads files with file(), templatefile(), or similar functions, stategraph config files records which files a change includes:

# Attach file globs to an address (takes the union with any existing globs)
stategraph config files attach --workspace default --address 'module.app.*' './templates/*.tpl'

# Remove specific globs (omit the globs to remove the whole address entry)
stategraph config files remove --workspace default --address 'module.app.*' './templates/*.tpl'

For the glob grammar, --dest, --expr, --recursive, and ephemeral tfvars, see Config Commands.

Common Options

Most subcommands accept these options, after the subcommand:

Output Format

Query and listing commands accept --format:

# JSON for scripting
stategraph states list --tenant <tenant-id> --format json | jq '.results[].name'

# Table for humans
stategraph states list --tenant <tenant-id> --format table

# Simple tab-separated for shell pipelines
stategraph user tenants list --format simple | awk '{print $1}'

tx subcommands always print JSON. They reject --format with unknown option --format.

Exit Codes

Next Steps

• User Commands: identity and tenant membership.
• States Commands: manage Terraform states.
• Terraform Commands: plan and apply through Stategraph.
• SQL Commands: query your infrastructure.
• Terraform CLI compatibility: how Terraform commands map to the CLI.
• API Reference: REST API documentation.