Saphan StudioDocs
Reference/Commands

saphan train

Shows and maintains trains: a train is a planned series of related work items, called wagons, declared in a train order and identified by its track name; each wagon is dispatched as its own stream.

Shows and maintains trains: a train is a planned series of related work items, called wagons, declared in a train order and identified by its track name; each wagon is dispatched as its own stream. saphan train next answers what can be started now, what is blocked and by what, and what is already in progress.

saphan train

saphan train backfill

Proposes which train and wagon each stream already in the record belongs to, with the evidence for each guess: the stream's own order, the train order, or the stream's name. Without --write it only proposes; with --write it records the new placements, which fill in a train or wagon the order left empty and never override one it declares.

saphan train backfill --train my-train --corpus /abs/bridge
saphan train backfill --train my-train --corpus /abs/bridge --write --actor <owner>
saphan train backfill --train <train>
flagtypedefaultwhat it does
--actorstringThe name recorded as confirming the placements under --write, taken as given; defaults to SAPHAN_ACTOR, then identity.actor.
--corpusstringThe checkout holding the train orders; defaults to $SAPHAN_TRAIN_CORPUS, and with neither the command refuses rather than reading the current directory.
--trainstringThe train to place streams in, by its train order's directory name or heading slug; this spelling is what the record stores.
--writeboolfalseRecord the proposed new placements in the record instead of only printing them; anyone who can run the command can pass it, and the named actor is recorded with each placement.

saphan train next

For one track, lists each wagon its train order declares with its state, rounds so far, last verdict, what blocks it and whether it is independent, then sorts every wagon into dispatchable now, blocked, or in flight, each with a ready-to-run next command. It also prints the three conditions for starting another wagon — an independent unstarted wagon exists, a seat (agent slot) is free, the coordinating agent is under its concurrency cap — and only reads, so it is safe in a loop. It covers only wagons named in the train order: an order never dispatched and named in no train order is invisible to it, as the printed population line says.

saphan train next --track <track>
flagtypedefaultwhat it does
--corpusstringThe checkout holding the train orders; defaults to $SAPHAN_TRAIN_CORPUS, and with neither the command refuses rather than reading the current directory.
--refstringRead the train orders as of this git ref instead of the working tree; defaults to $SAPHAN_TRAIN_CORPUS_REF.
--trackstringThe track to show, as named on the track: line of its orders.

saphan train rename

Gives a train a display name of your own; its slug never changes, and --clear returns it to the generated name.

saphan train rename <train-slug> --name <name>
flagtypedefaultwhat it does
--actorstringThe name recorded as renaming the train, taken as given; defaults to SAPHAN_ACTOR, then identity.actor.
--clearboolfalseReturn the train to its generated name: the order's heading, or the slug made readable.
--namestringThe display name, at most 80 characters.

saphan train wagon-edit

Edits the design of a wagon that has not been dispatched yet — title, cost quote, time budget, review mode, vendor and model, dependencies, allowed machines and preferred seat — and commits the new version of its order to the workspace's bridge repository. Use --dry-run to validate and preview the new header first.

saphan train wagon-edit my-train-w3 --quote 6 --wall 120m --review named --backend codex --model gpt-6-sol
saphan train wagon-edit <stream>
flagtypedefaultwhat it does
--actorstringThe name recorded as making the edit, taken as given; defaults to SAPHAN_ACTOR, then identity.actor.
--backendstringThe agent vendor for the wagon: claude-code or codex.
--bridgestringThe bridge directory holding the order; defaults to <workspace>/bridge.
--depends-onstringComma-separated wagon ids this wagon waits for; an empty value clears them.
--dry-runboolfalseValidate the edit and report whether the order would change, without writing anything.
--jsonboolfalseWith --dry-run, print the plan as JSON (path and the SHA-256 before and after), the values a passkey-confirmed save is bound to.
--machinesstringComma-separated machines the wagon may run on; this narrows the choice and never pins one. An empty value clears it.
--modelstringThe model to use, one the configuration accepts for the chosen vendor.
--prefer-seatstringThe seat to try first; a preference, never a pin. An empty value clears it.
--quotestringThe cost quote in US dollars; the wagon's spending cap is set to twice this amount.
--reviewstringThe review mode: named (a separate named review) or master-verify-only (only the coordinating agent's own verification).
--titlestringThe wagon's one-line title.
--wallstringThe wall-clock budget in minutes, written like 90m.

Global options apply to every command — see Every command.

saphan teardown

Archives a finished stream's channel files and records the teardown decision, the owner's recorded act that the stream's worktree may be removed.

saphan trust

Creates and manages the keys and signed records that establish who may instruct and approve work in an installation: the root key, delegations, the deployment record and edition, the owner's presence

On this page