@superrelay/cli

Command-line client for the Relay public REST API (/v1/public). Manage conversations, contacts, companies, products, feature requests, changelog entries, and knowledge bases from your terminal, sync a knowledge base with a folder of markdown files, and migrate data from Crisp.

Every command supports --json for machine-readable output. Full documentation lives in the docs site under API reference → CLI and Docs as code (apps/app-docs/content/docs/api-reference/).

Install

npm install -g @superrelay/cli
relay --help

Or run it without installing:

npx @superrelay/cli --help

Both relay and superrelay are installed as commands. Requires Node 20+.

Develop

From the repository root:

bun install
bun run apps/cli/index.ts --help

Or link it globally so relay is on your PATH:

cd apps/cli && bun link

Publish

cd apps/cli
bun run build          # bundles index.ts + deps into dist/index.js (Node shebang)
npm publish            # runs the build again via prepublishOnly

Configure

relay config --api-key rl_live_xxxxxxxx
relay config --api-url http://localhost:4000   # optional, for a local API
relay config --show

RELAY_API_KEY and RELAY_API_URL environment variables take precedence over stored config, which is what CI and agents should use.

Knowledge base sync

relay kb pull docs --kb "Acme Help Center"   # first time binds the folder
# edit the markdown files…
relay kb push docs --dry-run
relay kb push docs

Images and files linked with relative paths (![x](./images/a.png)) are uploaded on push and mapped back to relative links on pull; relay kb upload <file> uploads on its own and prints the URL.

The folder layout and conflict rules are in src/lib/kb-files.ts, src/lib/kb-sync.ts, and src/lib/kb-assets.ts; the planning logic is pure and covered by the tests next to it.

Knowledge bases that deploy from GitHub (3.3)

When a knowledge base is linked to a repository through Relay's GitHub App, the repository is the source of truth: merging to the linked branch deploys it, and edits made in Relay come back as a pull request on superrelay/<knowledge-base>-update. For such a knowledge base:

• relay kb push and relay kb stage refuse and name the repository and branch to merge to. The API refuses sync writes from older CLIs as well.

• relay kb status, diff and pull plan against the sync state Relay keeps (GET /v1/public/knowledge-bases/:id/sync-state) instead of .relay-kb.json, and pull writes no manifest. The GitHub App removes a committed .relay-kb.json in its pull request and adds it to the folder's .gitignore.

• check, preview, new and targets work as before; they never write.

• index.ts — command registration

• src/commands/ — one module per command group

• src/lib/api.ts — HTTP client; response types come from @relay/api-types, the same package the API's serializers are typed with

• src/lib/format.ts — human-readable output

• src/lib/config.ts — credential storage (conf)

Checks

bun run typecheck
bun test

Search and automation

relay conversations list --status open --priority urgent --all --json
relay contacts --email [email protected] --json
relay contacts --search billing --all --json
relay reply <conversation-id> --file reply.txt --json

Conversation search supports customer name/email, subject and public messages; private notes are excluded. Filter with --status, --priority, --assignee, --label, --contact and --product. Conversation prefixes resolve across the workspace and must be unique. Existing shortcuts such as relay list still work.

--timeout <ms> defaults to 30000 and --retries <n> defaults to two retries for transient read failures. Writes are not automatically retried. JSON results go to stdout, structured errors go to stderr, and failures exit nonzero, including a partially failed KB push. Paginated resource lists accept --all.

Feature requests and changelog

relay requests create --title "Dark mode" --description "Support dark themes"
relay requests update <request-id> --title "System-aware dark mode"
relay requests move <request-id> --status planned
relay requests link <request-id> https://github.com/acme/app/pull/42
relay changelog draft --file release.md --request <request-id>
relay changelog update <entry-id> --file revised-release.md
relay changelog publish <entry-id>

relay feature-requests also works. New requests are private by default; use --visibility public to expose one to customers. Creating a request requires feature_requests:write; changelog writes require changelog:write. Listing and resolving short IDs need the matching read scope. Content inputs support --file - for stdin. Create commands accept --key for repeatable operations. Publishing keeps the existing linked-request, voter-email and ticket effects; editing an entry does not publish it.

Knowledge-base review and project targets

relay --profile app-prod config --api-key rl_live_xxxxxxxx
relay --profile app-prod kb init docs --kb "App Help" --target production
relay kb pull
relay doctor
relay kb new "Getting started" --template how-to
relay kb check
relay kb status
relay kb diff
relay kb preview
relay kb stage
relay kb push --staged

relay.kb.json binds each target directory to its API URL, workspace, product, knowledge base and credential profile. Credentials stay outside Git. Use separate folders for staging and production; select one with --target. Existing unconfigured kb pull docs --kb <id> / kb push docs commands remain supported.

relay kb targets list shows destinations and profiles. relay kb targets use staging saves a new repository default without moving or publishing articles. Use --target for a one-command override. Review and commit changes to relay.kb.json intentionally.

relay doctor [dir] --target <name> checks credentials, API read access, destination bindings, server capabilities, local validation and pending recovery. It prints fixes and exits nonzero on failed checks. It never tests write permissions or resumes writes.

kb new "Title" creates a local draft with no remote ID. Templates are blank (default), how-to, troubleshooting, and faq. Use --file Billing/refunds.md for a category or nested path and --dir docs for an explicit docs root. Existing, ignored and escaping paths are rejected. No API key is needed.

kb diff shows unified hunks with three context lines and counts edits, new drafts, new published articles, deletions and blocked changes. JSON retains complete before/after content and adds patch and summary fields.

For validation on every pull request, copy examples/kb-check.yml to .github/workflows/kb-check.yml in each initialized app repository after CLI 3.2.1 is published. It runs kb check --all-targets --format github with file annotations, needs no Relay secrets, and never publishes. You can also use --all-targets --json.

Sync recognizes file moves by article ID, validates all files before new writes, checks remote revisions atomically, and checkpoints interrupted operations for idempotent recovery. A conflict fails CI even with --json; pruning never deletes an article through its former filename or overwrites a newer remote edit.

Article discovery is recursive, with the first folder level defining the category. .relayignore supports relative globs; .relay-category.json inside a category folder sets its name and order. Links to Markdown articles become help-center URLs, while other local assets are uploaded and cached by hash.

preview uses the API renderer and sanitizer without publishing. stage records reviewed changes locally; push --staged rejects changes after review. Plain push still applies edits to published articles immediately. Multi-article pushes are not atomic: preserve the manifest and written-back IDs for retries and CI. Deploy the updated API and docs service before using gradual publishing with CLI 3.2.

Full workflow: Docs as code.

Gradual publishing and recovery (3.2)

Published articles may link to drafts. Public docs and the widget show the link’s label as plain text until its destination is published. Change the destination to status: published and push; referring links return on the next load, without editing or repushing those articles. The original links stay in storage. The API must advertise draft-links; deploy the API and docs service before CLI 3.2. Authoring API responses and local previews retain draft links.

Generated article files must preserve the id: written by the first push. Round-trip IDs from each app’s destination files; do not share one app’s IDs across KBs. Commit files and the completed manifest together. If IDs were dropped:

relay --target cart kb check --restore-ids
relay --target cart kb diff Billing/refunds.md
relay kb targets remove obsolete
relay --target discounts kb init docs-discounts-v2 --kb "Discounts Help" --force
relay kb list --full-ids

--target works before or after kb. ID repair is offline and inserts only missing IDs from the manifest at their tracked paths. Existing conflicting IDs, moved files claiming an ID and pending writes stop repair. Use one target at a time. init --force can rebind a target to a fresh directory; it cannot reuse another KB’s manifest. Removing a target keeps its files and repairs the default.

kb diff <file> and kb diff --file <file> select a docs-root-relative article. Content comparison recognizes equivalent ID/slug link rewriting and timestamp-only changes, while actual remote edits still require review. Push errors name the file and suggest a diff. Manifest revisions use clean tokens on disk and quoted ETags on the wire; existing manifests remain compatible.

Category metadata belongs in <first-level-folder>/.relay-category.json: {"name":"Billing and payments","order":2}. Both fields are optional. name is 1–200 characters, defaulting to the folder name for new categories; order is a safe integer, with lower numbers first. Omitting either preserves existing values. Unknown fields are rejected. Nested folders share their first-level category; empty folders do not create categories.