CLI

The Stategraph CLI (stategraph) provides command-line access to Stategraph for automation, scripting, and programmatic workflows.

Installation

For day-to-day use, install the CLI directly using the install script, Homebrew, APT, or a binary download. Docker is also available as a distribution mechanism, but running the CLI inside a container requires extra setup (volume mounts, environment variables) — most users should install the binary directly.

See the releases page for available versions.

Install Script (macOS & Linux)

Install the latest version with a single command:

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 Stategraph repository and install:

# 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

Supported architectures: amd64 and arm64.

Binary Installation

Download the appropriate binary for your platform from the releases page:

After downloading:

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

Verify the installation:

stategraph --version
stategraph --help

stategraph --version prints the CLI version. stategraph-server --version does the same for the server binary. Running stategraph with no arguments shows a curated getting-started screen; stategraph --help shows the full command list with aliases.

Docker

The CLI is available as a Docker image. Check the releases page for available version tags.

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

Extract the binary from Docker

If you don't want to use Homebrew or curl, you can pull the binary out of the Docker image and use it natively:

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

For CI/CD pipelines or containerized environments, you can run the CLI directly inside Docker. This requires mounting your working directory and forwarding 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 for convenience:

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 pass it with each command (the flag goes after the subcommand):

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

Authentication

The CLI authenticates using API keys. Create an API key via the UI or API, then set it as an environment variable:

export STATEGRAPH_API_KEY="<your-api-key>"
stategraph user tenants list

API keys work as Bearer tokens. See Authentication for details on creating API keys.

Command Structure

stategraph <command> <subcommand> [options]

Available Commands

Every command group has a dedicated reference page:

Aliases

Six top-level aliases shorten the most common commands:

Quick Examples

Orient yourself (great for new users and AI agents)

stategraph info

Fetches the current user, server version, and tenant list in a single call. Prints suggested next steps when run in table or simple format.

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 this from the root of your Terraform module. Pass the same --var-file / --var flags you use with terraform plan:

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

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

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

See Velocity setup for the full import workflow.

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

Common Options

These options are available on most subcommands (passed after the subcommand, not before):

Managing attached data files

When your HCL reads external files (via file(), templatefile(), and similar), Stategraph needs
to know which files to include in a change. stategraph config files records these as globs in
stategraph.json, keyed by workspace and an address glob:

# 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'

The address glob uses the same grammar as --force / --force-files. See Config Commands for the full reference.

Output Format

Query and listing commands accept --format to choose between three output modes:

# 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 are the exception: they always emit JSON and do not accept --format (passing it returns unknown option --format).

Exit Codes

Documentation

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
• API Reference - REST API documentation