Configuration

Two state surfaces:

File	Purpose	Permissions	Carries secrets?
`~/.commstate/config.toml`	Preferences (API URL, default tenant, output format)	0600	No
`~/.commstate/credentials`	File-fallback credential store (only used if no OS keychain)	0600	Yes — keychain preferred

Override either path with env vars:

COMMSTATE_CONFIG=/path/to/config.toml          commstate whoami
COMMSTATE_CREDENTIALS_FILE=/path/to/creds      commstate whoami

Useful for tests, multi-profile setups, or running multiple CLI personas on the same machine.

Config keys

The config file is TOML. Missing fields fall back to defaults; unknown keys are silently ignored (so old binaries don't break when a new key lands).

api_url = "https://api.autocom.wexron.io/api/v1"
tenant  = "acme"
output  = "table"
ring    = ""               # optional ring pin; usually inferred from hostname
no_telemetry = false       # opt out of the version-check ping (planned)

Key	Default	Type	Description
`api_url`	`https://api.autocom.wexron.io/api/v1`	string	Base URL — no trailing `/graphql`
`tenant`	—	string	Default tenant slug for the `X-Tenant` header
`output`	`table`	enum	One of `table` / `json` / `yaml`
`ring`	—	string	Pin a deployment ring (rare; usually inferred from hostname)
`no_telemetry`	`false`	bool	Opt out of the periodic version-check ping (planned)

Reading and writing

commstate config list                            # show everything + the file path
commstate config get api_url                     # one value
commstate config set output json                 # update + save
commstate config set wat foo                     # ✗ exit 2: unknown config key

set validates: e.g. output must be one of the three valid formats; an unknown key fails fast. The file is written atomically (write-temp-then-rename), so a crash mid-save can't leave you with a corrupt half-file.

Override priority

For any value that has a config key + a flag + an env equivalent, the priority is:

command-line flag    >    environment variable    >    config file    >    built-in default

Examples:

# Use a different API for one command, without touching config
commstate --api-url https://api.staging.commstate.io/api/v1 orders list

# Switch tenant for one command
commstate --tenant widgets orders list

# Force JSON output regardless of config
commstate orders list -o json

Environment variables

Variable	Effect
`COMMSTATE_CONFIG`	Path to the config file (overrides `~/.commstate/config.toml`)
`COMMSTATE_CREDENTIALS_FILE`	Path to the credentials file fallback
`COMMSTATE_CLIENT_ID`	OAuth client ID for `auth login` (used when `--client-id` not passed and no build-time default)
`NO_COLOR`	Disable ANSI styling (also `--no-color` flag)
`BROWSER`	Custom browser launcher for OAuth flow (overrides OS default)

Multi-profile workflow

If you frequently switch between a personal sandbox and a production tenant, point each profile at its own config file:

# Personal sandbox profile
COMMSTATE_CONFIG=~/.commstate/sandbox.toml \
COMMSTATE_CREDENTIALS_FILE=~/.commstate/sandbox.creds \
  commstate auth login --api-url https://sandbox.commstate.io/api/v1 --tenant my-test

# Production profile
COMMSTATE_CONFIG=~/.commstate/prod.toml \
COMMSTATE_CREDENTIALS_FILE=~/.commstate/prod.creds \
  commstate auth login --api-url https://api.autocom.wexron.io/api/v1 --tenant acme

# Use shell aliases
alias commstate-sandbox='COMMSTATE_CONFIG=~/.commstate/sandbox.toml COMMSTATE_CREDENTIALS_FILE=~/.commstate/sandbox.creds commstate'
alias commstate-prod='COMMSTATE_CONFIG=~/.commstate/prod.toml COMMSTATE_CREDENTIALS_FILE=~/.commstate/prod.creds commstate'

commstate-prod orders list --status pending

The single-config workflow ALSO supports multiple environments — see Authentication → Multi-environment — but profiles are useful when each environment has its own preferred tenant and output format too.

File locations on each OS

OS	Default config	Default credentials
macOS	`~/.commstate/config.toml`	macOS Keychain (`commstate-cli` service)
Linux	`~/.commstate/config.toml`	Secret Service (gnome-keyring, kwallet, etc.)
Windows	`%USERPROFILE%\.commstate\config.toml`	Windows Credential Manager

The keychain holds a JSON blob keyed by api_url so you can have credentials for many environments without conflict.

Inspecting credentials

The CLI does not have a creds dump command — by design, since the goal is for the OS keychain to be the storage of last resort. To inspect what's stored, use the OS-native tool:

# macOS
security find-generic-password -s commstate-cli -a credentials -w

# Linux (Secret Service)
secret-tool lookup service commstate-cli account credentials

# File fallback (when no keychain)
cat ~/.commstate/credentials | jq .

Resetting

Wipe everything for a clean start:

commstate auth logout                       # clear keychain entry for current api_url
rm -rf ~/.commstate                         # nuke config + file fallback
unset COMMSTATE_CONFIG COMMSTATE_CREDENTIALS_FILE COMMSTATE_CLIENT_ID