CLI

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

Installation

The CLI is available via Homebrew, native binaries, and Docker. See the releases page for available versions.

Homebrew (macOS)

The easiest way to install on macOS:

brew tap stategraph/stategraph
brew install stategraph

To upgrade:

brew upgrade stategraph

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 Installation

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

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

Run commands using Docker:

docker run --rm ghcr.io/stategraph/stategraph:<version> stategraph --help

Or create an alias for convenience:

alias stategraph='docker run --rm -e STATEGRAPH_API_BASE ghcr.io/stategraph/stategraph:<version> stategraph'

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