Docs: align CLI surface with relay v9, add Relaycast API reference, cut fluff#18
Conversation
…ut fluff
- Update all CLI pages to the current command surface: the `local` group is
renamed to `node` (deprecated alias), workflow verbs live under
`node workflow run|logs|sync`, and `fleet serve` is replaced by
`node up --config`. Document real flags and defaults for `node up`,
`node down`, spawn/attach, plus the `fleet`, `cloud enroll`, `skills`,
and inbound-webhook commands and the `relay` binary alias.
- Add a Relaycast API reference page summarizing the OpenAPI spec behind
cast.agentrelay.com: base URLs, token auth, response envelope, endpoint
tables by group, WebSocket streams, and self-hosting.
- Tighten every current docs page for value per word: remove spec-speak
("Relay should..."), self-referential planning notes, and generic filler;
keep technical content matter-of-fact.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VrxGuDDDqLNfzGEAbfjC84
📝 WalkthroughWalkthroughThis PR renames the CLI local runtime to node runtime across docs, revises messaging and delivery guidance, and adds a new Relaycast API reference page with navigation support. ChangesCLI runtime and command reference
Messaging, delivery, and harness guidance
Relaycast API reference
Estimated code review effort: 3 (Moderate) | ~25 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
There was a problem hiding this comment.
Code Review
This pull request updates the documentation across several MDX files to reflect a transition from local commands to node commands, introduce the new Relaycast API reference, and streamline terminology (such as removing references to "version 8" and clarifying the use of workspace keys). The review feedback points out two consistency issues: using workspace key instead of API key in the new Relaycast API document, and using the kebab-case <run-id> placeholder instead of camelCase <runId> for cloud commands in the CLI reference.
Important
The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.
|
|
||
| | Method and path | Purpose | Auth | | ||
| | --- | --- | --- | | ||
| | `POST /workspaces` | Create a workspace (idempotent by name; API key returned on first creation only). | none | |
There was a problem hiding this comment.
To maintain consistent terminology across the documentation, use workspace key instead of API key. The documentation elsewhere explicitly states that no separate user API key is required and that the workspace key is the primary credential.
Suggested change:
| `POST /workspaces` | Create a workspace (idempotent by name; workspace key returned on first creation only). | none |There was a problem hiding this comment.
Fixed in 849fb7a — the row now says "workspace key returned on first creation only." (The spec's response field is named api_key, but the docs term for that credential is workspace key.)
Generated by Claude Code
| | `agent-relay cloud status <runId>` | Show cloud run status. | | ||
| | `agent-relay cloud logs <runId>` | Show cloud run logs. | | ||
| | `agent-relay cloud sync <runId>` | Sync local state with cloud. | | ||
| | `agent-relay cloud cancel <runId>` | Cancel a cloud run. | |
There was a problem hiding this comment.
For consistency with the local workflow run commands (which use <run-id>), use the kebab-case <run-id> placeholder instead of the camelCase <runId> for the cloud commands.
Suggested change:
| `agent-relay cloud status <run-id>` | Show cloud run status. |
| `agent-relay cloud logs <run-id>` | Show cloud run logs. |
| `agent-relay cloud sync <run-id>` | Sync local state with cloud. |
| `agent-relay cloud cancel <run-id>` | Cancel a cloud run. |There was a problem hiding this comment.
Leaving as-is: the placeholders mirror the CLI's actual help output. The cloud commands are registered with .argument('<runId>', 'Workflow run id') (relay repo, packages/cli/src/cli/commands/cloud.ts), while the node workflow commands use <run-id>. The inconsistency is in the CLI itself; if we normalize it there, the docs should follow.
Generated by Claude Code
|
Preview deployed!
This is a Cloudflare Workers preview version of this PR's build. |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 8ffc9b9ad1
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| | `POST /actions/{name}/invoke` | Invoke; returns `invocation_id` immediately (fire-and-forget). | workspace key or agent token | | ||
| | `POST /actions/{name}/invocations/{id}/complete` | Report a handler result. | agent or node token | |
There was a problem hiding this comment.
The OpenAPI spec linked from this page exposes both POST /actions/{name}/invoke and POST /actions/{name}/invocations/{id}/complete with agentToken security only. As written, callers will try workspace keys for invoke or node tokens for completion on the REST API and get rejected; node-side completion should be documented separately if it happens over the node control stream rather than this endpoint.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Confirmed against the spec and fixed in 849fb7a: both POST /actions/{name}/invoke and POST /actions/{name}/invocations/{id}/complete now show agent token only. The complete row also notes that node-hosted handlers reply with action.result frames over /v1/node/ws rather than this REST endpoint.
Generated by Claude Code
| | --- | --- | --- | | ||
| | `POST /dm` | Send a DM (`to` is an agent name). | agent token | | ||
| | `GET /dm/conversations` | List the acting agent's DM conversations. | agent token | | ||
| | `POST /dm/group` | Create a group DM. | agent token or workspace key | |
There was a problem hiding this comment.
The linked OpenAPI spec lists POST /dm/group under Direct Messages with only agentToken security. A workspace key has no acting DM participant, so users following this table with an rk_live_* key will hit an auth failure; this row should advertise agent-token auth only.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Confirmed against the spec and fixed in 849fb7a — POST /dm/group now shows agent token only.
Generated by Claude Code
There was a problem hiding this comment.
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
web/content/docs/cli-agent-management.mdx (1)
40-56: 📐 Maintainability & Code Quality | 🟠 Major | ⚡ Quick winHeadings still say "Local" despite the node rename.
## Start Local Runtimeand## Spawn Local Agentsretain "Local" wording while the commands underneath were renamed toagent-relay node ....cli-overview.mdxrenamed its equivalent section from "Local Runtime" to "Node Runtime" for the same rename effort, so these headings are now inconsistent with the sibling doc.✏️ Suggested heading fix
-## Start Local Runtime +## Start Node Runtime-## Spawn Local Agents +## Spawn Node Agents🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@web/content/docs/cli-agent-management.mdx` around lines 40 - 56, Update the headings in the docs section to match the node rename: the current “Start Local Runtime” and “Spawn Local Agents” titles in the markdown content still use old “Local” wording. Adjust these headings to the same “Node Runtime” terminology used by the sibling docs, keeping the surrounding command examples and explanatory text in sync with the renamed `agent-relay node ...` flow.
🧹 Nitpick comments (1)
web/content/docs/cli-overview.mdx (1)
122-124: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low valueInternal run-metadata path still uses "local-runs" naming.
.agentworkforce/relay/local-runsretains the oldlocalterm even though the surrounding CLI verbs and section title were renamed tonode. If this is the actual on-disk path used by the tool, leave it as-is (paths shouldn't be renamed just for doc consistency); flagging only in case the intent was to rename the directory too.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@web/content/docs/cli-overview.mdx` around lines 122 - 124, The docs text in the CLI overview still uses the legacy "local-runs" directory name while the surrounding verb was renamed to "node"; verify the actual on-disk metadata path used by node workflow run before changing anything. If .agentworkforce/relay/local-runs is the real runtime path, keep it unchanged and only clarify in the wording that it is a legacy directory name; otherwise update the path reference consistently in the CLI overview content.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Outside diff comments:
In `@web/content/docs/cli-agent-management.mdx`:
- Around line 40-56: Update the headings in the docs section to match the node
rename: the current “Start Local Runtime” and “Spawn Local Agents” titles in the
markdown content still use old “Local” wording. Adjust these headings to the
same “Node Runtime” terminology used by the sibling docs, keeping the
surrounding command examples and explanatory text in sync with the renamed
`agent-relay node ...` flow.
---
Nitpick comments:
In `@web/content/docs/cli-overview.mdx`:
- Around line 122-124: The docs text in the CLI overview still uses the legacy
"local-runs" directory name while the surrounding verb was renamed to "node";
verify the actual on-disk metadata path used by node workflow run before
changing anything. If .agentworkforce/relay/local-runs is the real runtime path,
keep it unchanged and only clarify in the wording that it is a legacy directory
name; otherwise update the path reference consistently in the CLI overview
content.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: eafe2dbb-f35a-4e84-807c-1e8f82616604
📒 Files selected for processing (21)
web/content/docs/agent-relay-mcp.mdxweb/content/docs/cli-agent-management.mdxweb/content/docs/cli-broker-lifecycle.mdxweb/content/docs/cli-messaging.mdxweb/content/docs/cli-overview.mdxweb/content/docs/delivery.mdxweb/content/docs/event-handlers.mdxweb/content/docs/harness-driver.mdxweb/content/docs/harnesses.mdxweb/content/docs/introduction.mdxweb/content/docs/messaging.mdxweb/content/docs/nodes.mdxweb/content/docs/quickstart.mdxweb/content/docs/reference-cli.mdxweb/content/docs/relaycast-api.mdxweb/content/docs/sending-messages.mdxweb/content/docs/session-capabilities.mdxweb/content/docs/typescript-sdk.mdxweb/content/docs/webhooks.mdxweb/content/docs/workspaces.mdxweb/lib/docs-nav.ts
💤 Files with no reviewable changes (1)
- web/content/docs/webhooks.mdx
There was a problem hiding this comment.
2 issues found across 21 files
Reply with feedback, questions, or to request a fix.
Re-trigger cubic
…xample-first
- Correct the Relaycast API auth column against openapi.yaml: action
invoke/complete and group DM creation are agent-token only, channel invite
is agent-token, node roster reads accept any token, spawn/release also
accept node tokens. Split the file and read-receipt rows so each endpoint
names its exact auth, define "any token" once, and note that node-hosted
action handlers reply over /v1/node/ws rather than the REST complete
endpoint. Clarify /hooks/{webhookId} is the URL POST /webhooks returns.
- Rewrite the introduction and quickstart example-first: one-sentence
positioning, working code in the first screenful, numbered quickstart
steps with one line of prose each. Concept detail moves to the pages
that own it.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VrxGuDDDqLNfzGEAbfjC84
There was a problem hiding this comment.
1 issue found across 3 files (changes from recent commits).
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="web/content/docs/introduction.mdx">
<violation number="1" location="web/content/docs/introduction.mdx:18">
P2: The intro code snippet sends to `#general` but no channel was created — readers who run the example verbatim may hit a 'channel not found' error if the SDK does not auto-create a default channel. Consider either (a) adding a `channels.create({ name: 'general' })` call before the send, or (b) sending to `#customer-complaints` after creating it (matching the quickstart pattern) so the example is correct as-is.</violation>
</file>
Reply with feedback, questions, or to request a fix.
Re-trigger cubic
| { name: 'engineer', type: 'agent' }, | ||
| ]); | ||
|
|
||
| await planner.sendMessage({ |
There was a problem hiding this comment.
P2: The intro code snippet sends to #general but no channel was created — readers who run the example verbatim may hit a 'channel not found' error if the SDK does not auto-create a default channel. Consider either (a) adding a channels.create({ name: 'general' }) call before the send, or (b) sending to #customer-complaints after creating it (matching the quickstart pattern) so the example is correct as-is.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At web/content/docs/introduction.mdx, line 18:
<comment>The intro code snippet sends to `#general` but no channel was created — readers who run the example verbatim may hit a 'channel not found' error if the SDK does not auto-create a default channel. Consider either (a) adding a `channels.create({ name: 'general' })` call before the send, or (b) sending to `#customer-complaints` after creating it (matching the quickstart pattern) so the example is correct as-is.</comment>
<file context>
@@ -1,24 +1,42 @@
+ { name: 'engineer', type: 'agent' },
+]);
+
+await planner.sendMessage({
+ to: '#general',
+ text: `${engineer.handle} pick up the next ticket.`,
</file context>
The frontmatter description renders as the page lede, so introduction.mdx and actions.mdx opened by restating it. Start both bodies at the first new information instead. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01VrxGuDDDqLNfzGEAbfjC84
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@web/content/docs/relaycast-api.mdx`:
- Line 36: The WebSocket auth note is too broad in the relaycast API docs and
should only apply to clients that cannot set headers. Update the wording in the
docs content around the WebSocket token usage so it says browser clients, or
more generally clients that cannot set headers, instead of implying all WS
clients cannot send headers. Keep the existing guidance about preferring headers
elsewhere.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: 45e867e9-de02-4171-b816-db3f5dcc9845
📒 Files selected for processing (4)
web/content/docs/actions.mdxweb/content/docs/introduction.mdxweb/content/docs/quickstart.mdxweb/content/docs/relaycast-api.mdx
✅ Files skipped from review due to trivial changes (1)
- web/content/docs/quickstart.mdx
| | Node token | `nt_live_*` | `POST /agent/node-token` (direct) or `POST /nodes` (fleet host) | | ||
| | Observer token | `ot_live_*` | `POST /observer-tokens` (workspace key required) | | ||
|
|
||
| Inbound webhooks additionally use a per-webhook `wh_live_*` bearer token. WebSocket endpoints accept the token as a `?token=` query parameter because WS clients cannot set headers; prefer the header everywhere else since query strings can land in access logs. |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# Locate the doc and related auth references.
git ls-files | rg 'web/content/docs/relaycast-api\.mdx|auth|websocket|ws|socket|openapi|api' || true
echo '--- relaycast-api excerpt ---'
sed -n '1,120p' web/content/docs/relaycast-api.mdx
echo '--- search for websocket token guidance elsewhere ---'
rg -n "query parameter|custom headers|cannot set headers|WebSocket|wh_live_|token=" web/content/docs web -g '!**/node_modules/**' || trueRepository: AgentWorkforce/agentrelay.com
Length of output: 30333
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# Show the relevant section with line numbers and nearby context.
nl -ba web/content/docs/relaycast-api.mdx | sed -n '20,60p'
echo '--- nearby auth references ---'
rg -n "wh_live_|WebSocket endpoints|cannot set headers|query strings can land in access logs|browser clients" web/content/docs -g '!**/node_modules/**' || trueRepository: AgentWorkforce/agentrelay.com
Length of output: 207
Scope the WebSocket auth note to clients that cannot set headers. web/content/docs/relaycast-api.mdx:36
WebSocket libraries in non-browser runtimes can set custom headers, so “WS clients cannot set headers” is too broad. Narrow this to browser clients, or say “clients that cannot set headers.”
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@web/content/docs/relaycast-api.mdx` at line 36, The WebSocket auth note is
too broad in the relaycast API docs and should only apply to clients that cannot
set headers. Update the wording in the docs content around the WebSocket token
usage so it says browser clients, or more generally clients that cannot set
headers, instead of implying all WS clients cannot send headers. Keep the
existing guidance about preferring headers elsewhere.
The introduction quickstart banner copy changed in #18; update the docs-markdown export assertion to the shipped text so the suite is green. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* Docs: nodes and providers Add the nodes-and-providers overview — workspace/agents/nodes/providers, action vs capacity registrations, node-addressed invoke, per-provider liveness, spawn wrapping, and the enroll + node up onboarding. Align the delivery, action, and CLI pages to the node-provider model: providers connect directly to the engine, the node's agent runtime hosts spawn/release capacity, and invocation is node-addressed. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * Fix stale introduction docs-export test assertion The introduction quickstart banner copy changed in #18; update the docs-markdown export assertion to the shipped text so the suite is green. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * Docs: address review feedback on nodes/providers pages - Use the direct `ctx.send_message` helper in the spawn-wrap example, matching the stated ctx surface and the sibling `ctx.spawn_agent` call. - Broaden the Capability glossary entry to cover both actions and capacity. - Say capacity is "never materialized as an invokable action" so it does not read as contradicting the action.invoke dispatch frames on the Actions page. - Fix "connects to /v1/node/ws" grammar. - Scope the orchestrating cross-reference to the shared invocation model. - Keep the harness-driver caller/host boundary explicit. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * Docs: align nt_live_* token notation on nodes-and-providers Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> --------- Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
Summary
Full review of the messaging-product docs against the current
relayandrelaycastrepos, plus a new API reference page and a value-per-word editing pass.CLI docs now match the shipped CLI (relay v9.2.1)
Verified every documented command against
packages/cli/srcin the relay repo:local→noderename. The docs described the deprecated surface. All examples now useagent-relay node up|down|status|metrics,node agent spawn|new|attach|release|set-model,node tail, and note thatlocalis a deprecated alias that warns.local run|logs|synctonode workflow run|logs|sync.fleet serveis gone — it is a stub that errors and points atrelay node up. The Nodes page now showsnode up --config ./builder.node.ts, theagent-relay.{ts,js,...}auto-discovery, andfleet nodes/fleet statusas the inspection commands.node up(--config,--broker-namedefault, port 3888, Cloud enrollment pickup,teams.jsonauto-spawn behavior),node down --timeoutdefault 5000 ms, spawn flags--cwd/--spawn-mode/--exit-after-task, attach mode defaults (new→drive,attach→view).cloud enroll,fleet config|enable|disable|inherit,skills add,integration subscribe|unsubscribe, inbound-webhook commands, and therelaybinary alias.New: Relaycast API reference (
/docs/relaycast-api)Summarizes the OpenAPI 3.0 spec behind
cast.agentrelay.comso readers have the REST/WS surface in one place: base URLs (hosted + self-hosted engine), bearer-token auth by prefix, response envelope and idempotency header, endpoint tables for every group (workspaces, agents, channels, messages, DMs, deliveries, files, actions, nodes, triggers, webhooks, subscriptions), both WebSocket streams, and a link to the full spec in the relaycast repo. Added under the Reference nav group.Value-per-word pass on every current page
Removed language that didn't increase reader understanding, without changing technical claims:
workspaceKey").Net: −199 lines of prose across 20 pages, +1 reference page.
Testing
npm test(web) — 21 passednpm run build— succeeds;/docs/relaycast-apiprerendered🤖 Generated with Claude Code
https://claude.ai/code/session_01VrxGuDDDqLNfzGEAbfjC84
Generated by Claude Code
Summary by cubic
Updates the docs to match the relay v9 CLI, adds a concise Relaycast API reference, fixes API auth per the OpenAPI spec, and tightens copy (intro/quickstart are example‑first; redundant ledes removed).
New Features
/docs/relaycast-api: OpenAPI-backed summary with base URLs, bearer auth, response envelope, endpoint tables, WebSocket streams, and self-hosting via@relaycast/engine(linked under Reference).relaybinary alias and new surfaces (inbound-webhook commands,skills add,node workflow *, fleet inspection/config, Cloud-managed node enrollment).Refactors
local→node(deprecated alias),fleet serve→node up --config, workflow verbs undernode workflow *. Documented real flags/defaults (node upport 3888, config auto-discovery,--broker-namedefault,teams.jsonauto-spawn, Cloud enrollment pickup;node down --timeout; spawn/attach flags and default modes). Expanded the command matrix withcloud enroll,fleet config|enable|disable|inherit, inbound-webhook subcommands, andnode tail./v1/node/wsand clarified that/hooks/{webhookId}is the URL returned byPOST /webhooks.Written for commit 403d275. Summary will update on new commits.