relay-cli

Production CLI for Relay. One command (relay) wraps the full HTTP surface: query the memory layer, pull the daily brief, manage atoms / conflicts / drift, upload meetings, manage API tokens, sync published skills, inspect retrieval traces.

The legacy relay-sync console script is preserved as an alias for relay skills sync so existing automation keeps working.

Install

pipx install ./cli            # recommended — isolated, on $PATH
# or
pip install -e ./cli          # editable, for hacking on the CLI

Optional extras:

pip install -e "./cli[yaml]"  # adds --output yaml support
pip install -e "./cli[dev]"   # adds pytest, pyyaml

First run

relay profile set prod --api-base https://api.relay.example --org acme --default
relay login --email you@acme.com
relay doctor

Environment variables (handy in CI):

Commands

relay login [--email --password|-] | [--with-token <jwt>]
relay logout
relay whoami

relay query ask "what is our refund SLA?"
relay query drift <query_log_id>

relay brief [--must-know N --must-do N --waiting N]

relay atoms list [--type --domain --search --limit --offset --include-inactive]
relay atoms list --all [--max 10000]   # auto-paginate every page
relay atoms get <atom_id>

relay conflicts list [--status]
relay conflicts resolve <id> --winner <atom_id> [--note "..."]

relay drift list [--status]
relay drift recompute

relay meetings list | get <id> | upload <file> [--title]

relay integrations status
relay integrations disconnect <kind>

relay export mine | create --kind atoms --format json | download <id> --out file

relay trace list | get <id>

relay tokens create --name ci --scope atoms:read --scope query:run
relay tokens list | revoke <id>

relay skills sync --org <slug> --target <dir> [--prune] [--dry-run]

relay profile list | set <name> | default <name> | show
relay welcome   # show the Relay banner (profile, API, auth state)
relay doctor
relay --version

Output formats

Every read command supports --output text|json|yaml|table. Default is text on a TTY, json on a pipe, so relay atoms list | jq just works.

Security notes

• Tokens live in the OS keyring (Keychain / Credential Manager / Secret Service). Fallback: ~/.config/relay/tokens/<profile> mode 0600 with a warning.
• Authorization is never echoed in -vv logs (httpx pinned to INFO).
• Skills-sync cache rejects any ETag that isn't hex-64 SHA-256.
• Writes are atomic via tmp + rename.

Tests

cd cli
python -m pytest