saphan order
Composes, signs and reads orders: the documents that tell an agent run what to do on a stream (one unit of work).
Composes, signs and reads orders: the documents that tell an agent run what to do on a stream (one unit of work). An order's authority is either a registration signed with a key file, or a person's security-key signature kept by the server; later checks read one or the other.
saphan order new
Prints the standing parts of a dispatch order for one stream, filled from the record: branch, base, repository and worktree, the model and limits in force, the round number and recent review verdicts, plus the base branch's local and remote commits as read now. The task, the reason and the definition of done are left as <FILL slots for you to write; acceptance criteria are never generated. The output passes saphan doc check --family order.
| flag | type | default | what it does |
|---|---|---|---|
--role | string | executor | The role the run is started as (default executor): one of master, executor, review, design, scribe or advisor, and any other value is refused; review produces the review variant of the order. |
--round | int | 0 | The round this order opens; by default one past the highest review round on record, and the document says which was used. |
--stream | string | The stream whose record fills the order. Required. |
saphan order replies
Lists, oldest first, the results order sign sent to an address when each signing draft ended (signed, refused or expired), with its orders and how long a signed authority runs. Nothing is consumed: the same results are listed until they are cleaned up.
| flag | type | default | what it does |
|---|---|---|---|
--json | bool | false | Print the results as JSON. |
--reply-to | string | The address to read, track:<slug> or a seat ID; defaults to the seat this session holds. |
saphan order show
Prints a registered order's exact bytes, read from the commit recorded when it was registered. Address it as slug@<hex> (at least 12 hex characters) or by its full 64-character digest. It refuses, by name, a reference that matches more than one registration, and a registration that is unknown, revoked, superseded (naming the replacement), expired, whose bytes no longer match, or larger than 64 KiB.
| flag | type | default | what it does |
|---|---|---|---|
--format | string | text (the default: the document on standard output, details on standard error) or json (details plus the document in base64). |
saphan order sign
Signs orders in one of two ways, and they write different things.
With --key it signs exactly one document (an order or a bridge write-set) with that key file and registers it, printing the reference it can be addressed by. ⚠ This is an owner act: it asks for the one-time code at your terminal, and it is refused without a terminal and in the console's browser terminal. The signature is written beside the file as <path>.sig, replacing any earlier one. The document must already be committed, or registration refuses with order-uncommitted (the signature file is kept). Signing does not decide whether the signature authorises anything; saphan verify checks that when the order is used.
Without --key a person approves the whole batch with one touch of a security key, in the browser or with --cli. Nothing is written beside the files and nothing is registered: the server records the signature over the exact bytes of each order, and it authorises them for --valid. Each file's kind is read from its name or its first heading (# ORDER —, # MASTER ORDER —, # REVIEW BRIEF —, # TRAIN ORDER —), its stream from that heading and its round from a - round: line; a file that gives none of these is refused before anything is written. The browser path needs gateway.listen set and the gateway serving its signing page, and is refused otherwise; nothing is ever sent unsigned.
| flag | type | default | what it does |
|---|---|---|---|
--actor | string | With --key only: the signing actor's label; defaults to SAPHAN_ACTOR, then your configuration. | |
--cli | bool | false | Sign on this terminal with a FIDO2 security key instead of in the browser; ignored with --key. The key must already be enrolled as your person credential (saphan person enrol). |
--expires | string | With --key only: when the registration expires, as an RFC 3339 time; without it the registration never expires. | |
--key | string | The private key file to sign one document with, root or delegate; the key ID is derived from the key itself. More than one path is refused. Omit it to have a person sign with a security key. | |
--kind | string | order | With --key only: the document kind, order (the default) or bridge-write-set. Without --key the kind is read from each file. |
--no-open | bool | false | Print the signing page's address instead of opening it in a browser; ignored with --key. |
--reply-to | string | Who is told when the draft is signed, refused or expires (track:<slug> or a seat ID; defaults to this session's seat); read it with saphan order replies. Browser signing only: refused with --key or --cli, and refused when it names no track or seat this workspace knows. | |
--slug | string | With --key only: the registration name, the readable half of the reference; defaults to the file's base name. | |
--ts | string | With --key only: the signing timestamp, RFC 3339; defaults to now. | |
--valid | duration | 4h0m0s | Without --key only: how long your authority over these orders lasts; 4 hours by default, at most 24. |
--wait | duration | 30m0s | Without --key only: how long to wait for the security-key touch before giving up; 30 minutes by default. |
Global options apply to every command — see Every command.