Commstate Docs

Commstate CLI

commstate is a single static binary that brings the platform to your terminal. It speaks GraphQL to the same /api/v1/graphql endpoint your web app uses, authenticates with the same identities, and respects the same RBAC permissions. There is no separate authority — everything is server-enforced.

Why a CLI

Three reasons it exists:

  1. Scriptability — commstate orders list -o json | jq slots into existing pipelines without you wrapping curl and parsing JSON yourself.
  2. Speed — Sub-50ms startup, one round-trip per command (GraphQL fetches exactly what you ask for; REST is the fallback for multipart and admin endpoints).
  3. Portability — Cross-compiled to macOS / Linux / Windows on amd64 + arm64. No Python, no Node, no PHP runtime needed on the user's machine.

Modeled after gh (GitHub's CLI) — same auth pattern, same Cobra command tree, same persisted-query optimization for hot commands.

Quick start

# 1. Install (see Installation for other methods)
brew install commstate/tap/commstate

# 2. Authenticate — opens your browser to the platform approval page
commstate auth login --tenant acme

# 3. Verify
commstate whoami
commstate health

# 4. Use it
commstate orders list --status pending --limit 20
commstate orders get ORD-20260503-0001
commstate api query '{ _schema { ring modules { alias version } } }'

What's in this section

Page What you'll find
Installation Homebrew, direct downloads, building from source
Authentication OAuth browser flow, paste-back fallback, PATs, multi-environment
Configuration ~/.commstate/config.toml, env vars, per-environment credentials
Commands Full reference for every subcommand and flag
Output Formats Table, JSON, YAML, TTY vs pipe behavior
Security Model What's protected by what, build hardening, threat model
Troubleshooting Common errors, exit codes, diagnostic commands

At a glance

  • Transport: GraphQL primary (POST /api/v1/graphql), REST fallback for multipart and a few admin endpoints
  • Auth: OAuth 2.0 authorization-code with PKCE (browser flow) — falls back to OOB paste-code for SSH; PATs for CI
  • Storage: Tokens in OS keychain (go-keyring); config at ~/.commstate/config.toml
  • Tenancy: Every request sends X-Tenant: <slug> resolved from --tenant flag → config → stored credential
  • Exit codes: Stable across versions — see Troubleshooting
  • Source: Lives at cli/ in the commstate monorepo, mirrors to commstate/core/cli

Related