Reading the CLI's output

For anyone who runs saphan at a terminal, from an agent, or from a script.

After reading it you can tell which form of output you are getting and why, find the full detail a short form left out, and answer the owner-presence prompt.

Three audiences, detected and never asked

Saphan decides who is reading. You are not asked, and there is no setting to pick.

A person can ask for more. --verbose gives a person the full form. Setting the variable by hand does the same for one command: SAPHAN_AGENT=manual saphan <verb> ….

--quiet prints only the first line. NO_COLOR, TERM=dumb and --color change colour only; they never change what is said.

--json output is unchanged by any of this.

The short form

A person at a terminal sees these parts, in this order:

1. A first line with a symbol. ✔ done · ✖ refused or failed · ⚠ done, with a warning · ● waiting.
2. A few lines about this act only.
3. Reason and Cause, on a refusal.
4. NEXT, with the exact commands to run. They are written without a leading $, so you can copy them.
5. Warnings.
6. One dim line, full detail: <path>, whenever anything was left out.

Four examples follow. Yours will differ in names and numbers.

Landed

✔ landed  my-stream  →  develop
  merge commit  3f9c2ab
  3 files changed

NEXT
  saphan teardown my-stream --workspace /work/acme

full detail: /work/acme/.saphan/logs/merge-20261012T094417Z.log

Not landed

✖ not landed  my-stream
  The stream has no recorded review verdict.

Reason  a named review is owed before this stream can land
Cause   no verdict is filed under this stream

NEXT
  saphan review my-stream --workspace /work/acme

full detail: /work/acme/.saphan/logs/merge-20261012T094102Z.log

Waiting for the code

● waiting  gate stop2  my-stream
  This act needs the owner present.

  Enter the code:

A table

✔ 3 machines

  MACHINE   STATE     SLOTS
  m-one     ready     2 / 4
  m-two     ready     0 / 4
  m-three   retired   -

full detail: /work/acme/.saphan/logs/machine-list-20261012T094733Z.log

Where the rest goes: the log

Everything the short form leaves out is written to a log:

<workspace>/.saphan/logs/<verb>-<UTC timestamp>.log

The last line of the short form, full detail: <path>, names the file. It appears only when something was left out.

A log that cannot be written never fails the command. You get one warning saying so, and the act carries on.

Owner acts show one stream

saphan accept, land, merge, gate and teardown are acts on one stream, and they show only that stream. Deviations elsewhere in the fleet are not printed by them. The act names the command that lists them: saphan bus reconcile.

The owner-presence prompt

The acts listed in Acts that need the owner present ask for a code before they write anything. The prompt waits for you:

• It is printed once.
• Enter with no code does not cancel. It asks again.
• A wrong code prints one line and asks again.
• Only three things cancel the act: Ctrl-C, closing the terminal, or 5 wrong codes.
• A cancel writes nothing.
• The same code is valid for the whole act. An act that needs the owner in several steps does not ask again.

So pressing Enter by habit does not leave the prompt. To leave it, press Ctrl-C.

Related

• Acts that need the owner present
• Every command