CLI (./relay)

./relay is a single, zero-dependency tool (Python 3 stdlib only) that drives a board over its REST API. Human-readable output by default; add --json for machine output. Any error exits non-zero.

Commands

The AI result blob

./relay result takes a JSON object with three optional keys, and nothing else — the card drawer renders exactly these:

{
  "summary": "- **One door** for everyone…",
  "changes": ["Adds a summary to the card drawer"],
  "screens": [
    { "url": "/attachments/135e5539-e4e9-4fd6-aa7a-5863ec683e4c",
      "caption": "Sign in — one email field" }
  ]
}

summary is markdown; changes is a list of strings (short verb phrases); screens is a list of objects with url and an optional caption.

A screen's url is the image itself, not the page it was taken on. Upload the screenshot and use the path attach prints:

url=$(./relay attach RLY-12 tmp/smoke/01-door.png --field url)   # → /attachments/<uuid>

Any other key — deploy_url at the top level, image / shot / path / name inside a screen — is refused with 422 invalid_ai_result naming what you wrote and what exists. The refusal is the point: a blob the drawer can't read renders an empty Screenshots strip, silently.

Depending one card on another

Dependencies exist to head off parallel implementations of the same thing, which land as bad merges. Two shapes make one:

1. Producer → consumer. Card A creates a thing; card B uses it: ./relay depends B A.
2. Co-creation. Two cards both need a thing that doesn't exist yet. Left alone, each builds its own version. Name one card the producer and point the other at it — or split the thing into its own card and depend both on it.

Touching the same file with no shared new thing is not a dependency; leave those parallel. A blocked card is undispatchable until every blocker reaches a top-level Done column, so link only what you mean.

Long arguments

Text arguments accept - to read from stdin or @path to read from a file, so specs and plans can be piped in:

./relay spec RLY-12 @spec.md
git log -1 --format=%B | ./relay comment RLY-12 -

Every --json command also takes --field PATH to print a single dotted-path value bare — ./relay card RLY-12 --field status prints working, with no quotes and no jq.

Keeping ./relay current

Relay owns five files in your project — ./relay, the three relay-* skills, and relay.md — and your board serves them at GET /api/scaffold. They are Relay's, never yours, so an update overwrites them unconditionally; nothing else in .claude/ is ever touched.

./relay update --check    # served vs. local version, and what would change. Writes nothing.
./relay update            # apply
./relay update --starter-only --base origin/trunk   # only the starter runner.json + prepare hook

The ./relay your board serves has the board's URL baked into its BOARD_URL line, so it needs no RELAY_URL; an exported RELAY_URL overrides it, and ./relay update (and auto-update) keep a project's baked URL.

The manifest's version is derived from the files' content, so it moves exactly when they do. What gets written is decided by content, not by that version: ./relay update hashes all five files against the manifest on every run and writes the ones that differ, so "this project is current" means "nothing needs writing". A deleted skill comes back, and so does an edited one — these five are Relay-owned, so a local change to them is damage to repair, not a customisation to keep. A version that has moved while the bytes already match writes nothing but the recorded version itself (the normal state after ./relay start self-updates).

./relay start also keeps itself up to date (RE185). Each heartbeat reply names latest_runner_version — the RUNNER_VERSION of the ./relay the board actually serves — and when the runner is behind it downloads that file, verifies it parses, writes it over its own ./relay, and restarts at a job boundary, so a running node is never interrupted. A download that will not compile is refused and the previous version keeps running, and a ./relay with local modifications this runner did not write is never overwritten.

Two .relay/runner.json keys control it:

Publishing is now coupled to deploying: the scaffold is built into the app's image, so a skill or CLI fix reaches projects when the app ships, and there is nothing to publish by hand.

For the autonomous runner and its operating rules, see the runner.

Usage limits

./relay start reads Claude subscription usage from the jobs it already runs. When usage passes a configured fraction of a window, it stops claiming. Jobs in flight finish. The runner reports itself RATE LIMITED to the board and resumes when the window resets. It also resumes earlier if a probe every 15 minutes shows usage has dropped. If Claude refuses a call outright, the runner pauses until the reset even with no limits configured.

Any other key inside limits, or a value outside 0–1, makes relay start refuse to start and name the key.

Runner config

./relay update creates .relay/runner.json when it is missing, documented inline: every key carries a comment, and the worktrees block starts commented out. A line whose first non-whitespace characters are // is a full-line comment; a trailing // after a value and /* */ block comments are not supported. The file is yours to tune and commit — update never overwrites it.

Worktree hooks. "worktrees": {"prepare": ".relay/prepare-worktree.sh", "cleanup": ".relay/cleanup-worktree.sh"} (those are also the defaults). prepare warms a new per-card worktree, and a failure fails the run. cleanup runs right before the runner deletes one, to stop per-worktree servers or databases; it is best-effort (a failure is logged and the tree is removed anyway), times out after 120s, and must be safe to run twice. A flat top-level "prepare" still works but is deprecated.

Flows as data

A board's flows — which stages are AI-enabled, what each node does, model/effort, retry and loop budgets — are edited in Settings › Stages (the stage's FLOW band), or pulled and pushed as data:

./relay flow code --json > code.json   # nodes, edges, trigger as stage names, isolation, version
./relay flow-push code code.json

An unchanged push bumps nothing; an edited one bumps the version like an editor save. Include the pulled version to get compare-and-swap (a 409 means the flow moved under you — re-pull, re-apply, push again); omit it for last-write-wins.

Two rules keep custom nodes safe: a node's command should start by checking out the card's branch (from vars.branch) and end by committing. A task loop (foreach: card.tasks) binds one task per iteration; each loop node fetches its task's body with {relay} task show {ref} {task_id} ({task} is its title). Legacy card.sub_tasks / sub_tasks / {sub_task_id} names are normalized to tasks when a flow is loaded or pushed.