Commands

Top-level help is always one keystroke away:

commstate --help
commstate <command> --help
commstate <command> <subcommand> --help

This page is the human-curated reference. The output of --help is the source of truth — flag names and defaults are guaranteed to match the binary.

Global flags

These work on every command:

Flag	Description
`--api-url <url>`	Override the configured API base URL for this invocation
`--tenant <slug>`	Override the configured tenant for this invocation
`-o, --output <fmt>`	One of `table`, `json`, `yaml`
`--config <path>`	Path to config file (or set `COMMSTATE_CONFIG`)
`--no-color`	Disable ANSI styling (or set `NO_COLOR=1`)
`-v, --verbose`	Verbose logging (planned)
`-h, --help`	Help for this command

auth

Manage CLI authentication. See Authentication for the deep dive.

auth login

commstate auth login [flags]

Default flow opens your browser to the platform's OAuth approval page (PKCE-protected, RFC 7636), redirects to a 127.0.0.1:<port>/callback listener, and exchanges the code for an access token.

Flag	Description
`--tenant <slug>`	Default tenant slug to send with subsequent commands
`--api-url <url>`	API base URL (also persisted to config)
`--client-id <uuid>`	OAuth client ID (defaults to `COMMSTATE_CLIENT_ID` or build-time default)
`--no-browser`	Skip browser launch — print URL and prompt for paste-back
`--with-token <PAT>`	Skip OAuth — supply a personal access token directly
`--token-stdin`	Read token from stdin (use with `--with-token=` empty)
`--timeout <secs>`	OAuth timeout (default 300)

auth logout

commstate auth logout

Forgets credentials for the current api_url. Removes from BOTH keychain and file fallback.

auth whoami

commstate auth whoami       # or top-level: `commstate whoami`

Reads the stored credential — no network round-trip. Shows name, email, api url, tenant, and a warning if the token has expired.

tenants

commstate tenants list                  # list memberships
commstate tenants use <slug>            # set default tenant

orders

Day-to-day order operations. Resolves through the GraphQL gateway via auto-derived orders_* fields (Bus::call('Orders', 'orders.<method>', ...)).

orders list

commstate orders list [--status <status>] [--limit <n>]

Flag	Default	Description
`--status`	—	Filter: `pending`, `confirmed`, `processing`, `ready_to_ship`, `shipped`, `out_for_delivery`, `delivered`, `cancelled`, `failed`
`--limit`	20	Max rows to return

commstate orders list                                          # default 20 rows
commstate orders list --status pending --limit 50
commstate orders list -o json | jq '.[] | {id, total}'
commstate orders list -o yaml > orders-snapshot.yaml

orders get

commstate orders get <order-id-or-number>

Detail view. v1 always renders JSON because module SDL fragments aren't shipped yet — typed table view lands in v1.2.

orders cancel

commstate orders cancel <order-id> [--reason <text>]

Sets status to cancelled. Reason is sent to notification rules — visible to the customer if their notification template includes it.

api

Raw GraphQL access — escape hatch for anything not yet wrapped in a friendly subcommand.

api query

commstate api query [QUERY] [flags]

The query body comes from one of (priority order):

commstate api query '{ _schema { ring } }'                     # positional arg
commstate api query -f my-query.graphql                        # file
commstate api query --stdin <<< '{ _schema { ring } }'         # stdin
commstate api query --persisted abc123def456...                # registered hash

Variables can be JSON inline or from a file:

commstate api query -f q.graphql -V '{"id":"abc"}'
commstate api query -f q.graphql --variables-file vars.json

Flag	Description
`-f, --file <path>`	Read query from file
`--stdin`	Read query from stdin
`-V, --variables <json>`	Inline JSON variables
`--variables-file <path>`	Read variables from JSON file
`--persisted <hash>`	Execute by sha256 hash — skips the query body

The full GraphQL response envelope is emitted on stdout. Pipe through jq for the data path you want.

config

Read and write CLI configuration. See Configuration for the key reference.

commstate config get <key>
commstate config set <key> <value>
commstate config list

health

commstate health

Anonymous probe of <host>/api/health. Reports ring, lock_path, and per-service status (database: up, redis: up). Useful as a CI gate to confirm an API is reachable before running the rest of a pipeline.

version

commstate version

Prints version + git commit + build date. Build identity is injected at link time — see Installation → From source.

upgrade

Self-update — see Upgrading & Versioning for the full flow.

commstate upgrade --check                        # what's available
commstate upgrade                                # apply latest
commstate upgrade --target 1.2.3                 # specific version
commstate upgrade --dry-run                      # verify but don't replace
commstate upgrade --force                        # reinstall over current

Flag	Description
`--check`	Read-only — print version comparison + release notes excerpt
`--force`	Reinstall even when already on latest
`--target <ver>`	Install a specific version (default: latest)
`--dry-run`	Download + verify SHA256 but skip the binary replace
`--allow-homebrew`	Bypass the Homebrew-install guard

whoami

Top-level alias for commstate auth whoami. See above.

completion

Cobra-generated shell completions:

commstate completion bash
commstate completion zsh
commstate completion fish
commstate completion powershell

See Installation → Shell completion for install paths.

Exit codes

Stable across versions — see Troubleshooting → Exit codes.