The relay binary

The relay command wraps @ganderbite/relay-core in a terminal-facing binary. It handles provider selection, pre-run banners, live progress, and error display. Every command exits with a documented code so CI scripts can distinguish auth failures from step failures.

Install

npm install -g @ganderbite/relay

Requires Node ≥ 20.10. If relay isn't found after install, ensure your npm global bin directory is on PATH (npm bin -g tells you where it is).

relay init

Probes auth and writes ~/.relay/settings.json. Without it, every other command exits with NoProviderConfiguredError (exit 6).

relay init
relay init --provider claude-cli   # non-interactive
relay init --force                 # overwrite existing settings

Today there is one provider — claude-cli, which runs Claude under your Claude subscription via the local claude binary. There is no API-key billing path in v1.

relay doctor

Six-section pre-flight: Node version, claude binary, .relay directory writeability, providers, auth probe, and resolved provider. Run it whenever something is off.

●─▶●─▶●─▶●  relay doctor

 ✓ node              v20.11.1
 ✓ claude binary     /usr/local/bin/claude  v1.2.0
 ✓ .relay dir        writable
 ✓ providers         claude-cli (subscription)
 ✓ auth              max subscription
 ✓ resolved          claude-cli

all checks passed

Exit codes: 0 when everything passes, 3 if only the API-key billing guard is blocking, 1 for any other blocker.

relay run

Execute a flow from start to finish. <flow> is either a directory path or a catalog flow name.

relay run codebase-discovery --repoPath=. --audience=dev
relay run ./packages/flows/codebase-discovery --repoPath=.

Flags:

Pre-run banner:

●─▶●─▶●─▶●  relay

flow     hello-world v0.1.0
input    the water cycle
run      a1b2c3  ·  2026-04-23 09:14Z
bill     subscription (max)  ·  no api charges
est      $0.00  ·  2 steps  ·  ~2 min

press ctrl-c any time — state is saved after every step.
───────────────────────────────────────────────────────

 ⠋ greet           sonnet     turn 1

Success banner:

●─▶●─▶●─▶●  hello-world · a1b2c3  ✓

 ✓ greet           sonnet     3.1s    $0.000
 ✓ summarize       sonnet     5.4s    $0.000

all 2 steps succeeded in 8.5s

cost     $0.000  (estimated api equivalent; billed to subscription)
output   .relay/runs/a1b2c3/greeting.md

relay resume

Resume from the last checkpoint. Steps that already succeeded are not re-executed; only the failed step and anything downstream of it run.

relay resume f9c3a2

●─▶●─▶●─▶●  relay resume f9c3a2

flow     hello-world v0.1.0
picking up from: summarize

 ⠋ summarize       running

spent so far: $0.000

The rule: a step shown as ✓ in the pre-resume banner is cached. It will not re-execute and its cost is not re-incurred. Only failed or pending steps run again.

relay runs

List recent runs in the current directory's .relay/runs/.

●─▶●─▶●─▶●  recent runs

 ✓  f9c3a2    codebase-discovery v0.1.0    2h ago      11m 42s
 ✕  a1b2c3    codebase-discovery v0.1.0    3d ago      0s
 ⊘  d4e5f6    codebase-discovery v0.1.0    1w ago      -

resume any: relay resume <runId>

Flags: --limit N (default 20), --status <state> to filter.

relay logs

Print the structured event log for a run.

relay logs f9c3a2                # full log
relay logs f9c3a2 --step inventory  # only one step

relay new

Scaffold a new flow package.

relay new my-audit                   # interactive (via generator skill if available)
relay new my-audit --template blank  # write a minimal one-step skeleton
relay new my-audit --template linear # two-step linear flow
relay new my-audit --template fanout # parallel example

●─▶●─▶●─▶●  relay new my-flow (blank template)

 ✓ wrote ./my-flow/package.json
 ✓ wrote ./my-flow/flow.ts
 ✓ wrote ./my-flow/prompts/01_first.md
 ✓ wrote ./my-flow/README.md
 ✓ wrote ./my-flow/tsconfig.json
 ✓ installed dev dependencies

try it:
    cd my-flow && relay run .

Catalog: list · search · install · upgrade

The catalog commands deal with shared flows published to npm under @ganderbite/flow-<name>.

●─▶●─▶●─▶●  installed flows (./.relay/flows/)

 codebase-discovery    v0.1.0    20m  $0.40   PM-ready report on an unknown repo
 api-audit             v0.2.1    15m  $0.25   surface stale or risky HTTP routes

2 flows installed. search more: relay search <query>

Authoring: validate · test · publish · dry-run

Once you start writing your own flows, these are the loop you use most.

relay --help glossary

flow        a named, versioned sequence of steps you can run
step        one node in a flow (prompt, script, branch, parallel, loop, ask, terminal)
handoff     the JSON one step produces and a later step consumes
run         one execution of a flow; identified by a run id
checkpoint  the saved state of a run after each step completes

Exit codes

Every code is stable across releases. CI scripts can rely on exit 3 to mean "auth misconfigured" and exit 4 to mean "a step's handoff was the wrong shape".

To put this together with a real flow, read Author a flow.