Stations

CLI reference

Every stations command form, generated from the CLI catalog.

GENERATED FILE — do not hand-edit. Source: scripts/lib/docs-cli-reference.ts. Regenerate with npm run docs:reference, then npm run docs:content.

The stations CLI talks to the same Gateway your browser does. One package, two commands — stations and stations-mcp — built as a tarball from the prepared workspace and installed globally. It is not published on the public npm registry, so npx stations will not install it; /docs/harness has the three lines that do. Mint a Settings token for a human session, or an agent stn_ key in Admin → Members.

This page is generated from the same COMMANDS catalog --help prints. An uncatalogued form cannot appear here, and a form that appears here is routable.

login

Store a stn_ token (0600); keeps apiUrl; --api-url persists

No Gateway request. Runs before a token is resolved.

No flags.

whoami

Token principal (actor / tenant / kind)

Gateway /bff. A Settings token is enough.

No flags.

boards list

List boards

Gateway /bff. A Settings token is enough.

No flags.

board show

Show a board

Gateway /bff. A Settings token is enough.

No flags.

cards list

List cards on a board

Gateway /bff. A Settings token is enough.

  • --board <id> (required) — Board id or slug.

card show

Show a card

Gateway /bff. A Settings token is enough.

No flags.

card create

Create a card (lands at the board's first station)

Gateway /bff. A Settings token is enough.

  • --board <id> (required) — Board id or slug.
  • --title <t> (required) — Card title.
  • --description <d> — Optional card description.

card attach-child

Make --child a child of --parent (the parent waits)

Gateway /bff. A Settings token is enough.

  • --parent <cardId> (required) — Parent card id.
  • --child <cardId> (required) — Child card id.

card detach-child

Remove a child edge; the child card itself is kept

Gateway /bff. A Settings token is enough.

  • --parent <cardId> (required) — Parent card id.
  • --child <cardId> — Child card id.
  • --relation <id> — Relation id, instead of --child.

board structure

The board's structure as the apply document it is

Gateway /bff. A Settings token is enough.

No flags.

board apply

Reconcile a structure document onto a board

Gateway /bff. A Settings token is enough.

  • --document <json> — The structure document itself, as JSON.
  • --file <path> — Read the document from a file.
  • --project <id> — Apply into this existing project.
  • --board <id> — Reconcile onto this existing board.
  • --dry-run — Report what would change and write nothing.

claim next

Claim the next card; --board lets the engine pick the station

Gateway /agent/v1. Needs an agent key.

  • --station <id> — Only claim at this station.
  • --board <id> — Let the engine pick the station on this board.

claim

Claim a card

Gateway /agent/v1. Needs an agent key.

No flags.

heartbeat

Heartbeat an active claim

Gateway /agent/v1. Needs an agent key.

No flags.

complete

Complete a claimed card

Gateway /agent/v1. Needs an agent key.

No flags.

artifact attach

artifact attach <cardId> --key <k> --kind <url|text|file> --value <v>

Gateway /agent/v1. Needs an agent key.

  • --key <k> (required) — Artifact key.
  • --kind <url|text|file> (required) — Artifact kind.
  • --value <v> (required) — Artifact value.

card comments

The card's comment thread, oldest first (discussion, not the audit trail)

Gateway /agent/v1. Needs an agent key.

No flags.

card comment

Append a comment as the token actor. Append-only: no edit, no delete.

Gateway /agent/v1. Needs an agent key.

  • --body <text> (required) — Comment body.

release

Release an active claim; the card is claimable again

Gateway /agent/v1. Needs an agent key.

No flags.

skills

List the SKILL.md recipes and the directory they are in

No Gateway request. Runs before a token is resolved.

  • --path — Print only the directory.

skills show

Print one recipe to stdout, for a harness with no skills directory

No Gateway request. Runs before a token is resolved.

No flags.

dispatch run

Wait for work, claim one card, start a runner, heartbeat, release on failure

Gateway /agent/v1. Needs an agent key.

  • --station <id> — Only claim at this station.
  • --board <id> — Only claim on this board.
  • --exec <cmd> — argv runner command.
  • --runner <claude|cursor|codex> — A thin argv preset.
  • --post <url> — HTTP runner URL.
  • --header <'K: V'> — HTTP runner header. Repeatable. env:NAME is read at run time.
  • --interval <seconds> — Poll gap when there is no work (default 15).
  • --run-timeout <seconds> — Give up on a run and release (default 0 = none; 3600 for --post).
  • --once — Stop after one card.
  • --max-cards <n> — Stop after n cards.
  • --serve-hook <port> — Also receive card.arrived_at_station.
  • --hook-path <path> — Hook path (default /stations/wake).
  • --hook-host <host> — Hook bind host (default 0.0.0.0).
  • --hook-secret-env <VAR> — Env var holding the whsec_ secret.

dispatch runners

Print the presets as the argv they are

No Gateway request. Runs before a token is resolved.

No flags.

dispatch install

Render a user service so the wait loop is not a gist

No Gateway request. Runs before a token is resolved.

  • --format <systemd|launchd> — Unit format.
  • --write — Write the unit to disk at 0600.