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:

Platform File
macOS (Apple Silicon) stategraph-macos-arm64.tar.gz
macOS (Intel) stategraph-macos-amd64.tar.gz
Linux (amd64) stategraph-linux-amd64.tar.gz
Linux (arm64) stategraph-linux-arm64.tar.gz

After downloading:

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

Verify the installation:

stategraph --help

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:

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

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 tenant list

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

Command Structure

stategraph <command> <subcommand> [options]

Available Commands

Command Description
stategraph user User management and identity
stategraph states State management operations
stategraph tx Transaction management
stategraph mql MQL query interface
stategraph tenant Tenant management including gap analysis

Quick Examples

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

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

Run an MQL query

stategraph mql query "SELECT r.type, count(*) FROM resources r GROUP BY r.type ORDER BY r.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

Global Options

Option Environment Variable Description
--api-base STATEGRAPH_API_BASE Base URL for API calls
- STATEGRAPH_API_KEY API key for authentication
--loggers STATEGRAPH_LOGGERS Logging configuration
-v, --verbose - Increase log verbosity

Output Format

Most commands output JSON for easy parsing:

stategraph states list --tenant <tenant-id> | jq '.results[].name'

Some commands output tab-separated values for quick viewing:

stategraph user tenants list
# Output: <id>    <name>

Exit Codes

Code Meaning
0 Success
1 Authentication error (Unauthorized)
2 Bad request (invalid input)

Documentation

Topic Description
User User identity and tenant membership
States State management commands
Transactions Transaction commands
MQL Query commands
Tenant Tenant and gap analysis

Next Steps