Relay docs

The superrelay-cli is a command-line tool built on the Relay public REST API (/v1/public). It lets you manage conversations and contacts from your terminal or scripts — and migrate your data from Crisp in one command (see Migrate from Crisp).

Every command supports --json for machine-readable, jq-friendly output, so it works well in CI and for scripting AI agents.

Install

Requires Bun.

git clone https://github.com/helloastral/superrelay-cli
cd superrelay-cli
bun install
bun link        # exposes `relay` / `superrelay` globally (optional)

Or run directly without linking: bun run index.ts <command>.

Configure

Create an API key in Settings → API Keys (it looks like rl_live_…), then:

relay config --api-key rl_live_xxxxxxxx
# optional: point at a self-hosted / local API
relay config --api-url http://localhost:4000
relay config --show

Credentials are stored in the platform config directory. For CI, the RELAY_API_KEY and RELAY_API_URL environment variables take precedence over stored config.

Scopes apply to the CLI too

The key's scopes are the authorization boundary: conversations:read, conversations:write, contacts:read, contacts:write. A command fails with a permission error if the key lacks the scope it needs.

Conversation commands

IDs accept a short prefix — the CLI resolves it against your recent conversations, so you rarely need to paste a full UUID.

Command	Description
`relay list` (`ls`)	List conversations (`--limit`, `--cursor`)
`relay show <id>`	Conversation details
`relay chat <id>`	Message history (`--limit`, `--cursor`)
`relay reply <id> <msg>`	Send an agent message (`--agent <userId>`, `--incoming`)
`relay resolve <id>`	Mark resolved
`relay reopen <id>` (`unresolve`)	Set status open
`relay pending <id>`	Mark pending
`relay priority <id> <level>`	`low` \| `medium` \| `high` \| `urgent` \| `none`
`relay label <id> [labels...]`	Replace labels (no args clears them)
`relay assign <id> [userId]`	Assign (`--unassign` to clear)
`relay create --contact <id>`	New conversation (`--inbox <id>`)

Contact commands

Command	Description
`relay people` (`contacts`)	List contacts (`--limit`, `--cursor`)
`relay person <id>` (`contact`)	View a contact
`relay contact:create`	Create (`--name`, `--email`, `--shop`)
`relay contact:update <id>`	Update (`--name`, `--email`, `--shop`, `--store <id\|none>`)

Store commands

Command	Description
`relay stores`	List stores (`--limit`, `--cursor`, `--search`)
`relay store <id>`	View a store (incl. contact count)
`relay store:contacts <id>`	List a store's contacts
`relay store:create`	Create (`--name`, `--website`, `--industry`, `--notes`)
`relay store:update <id>`	Update (`--name`, `--website`, `--industry`, `--notes`)

Examples

# Reply to the most recent unresolved conversation (short id prefix)
relay reply 9b2c "Thanks for reaching out — taking a look now."

# Triage: set priority and labels, then assign
relay priority 9b2c high
relay label 9b2c billing vip
relay assign 9b2c user_2x9Q

# Pipe machine-readable output into jq
relay list --json | jq '.data[] | {id, status, contact: .contact.name}'

Notes

The CLI talks only to Relay's authenticated public API; the key's scopes are the authorization boundary.
Output is plain text on errors, and --json is jq-friendly for scripting and AI agents.

CLI