Reference
Every command
The whole command surface: every command, its subcommands, and where each one is documented.
Saphan Studio is driven by one command, saphan. Each command below names the thing you act on; its
subcommands name what you do to it.
This reference covers 98 commands, 272 subcommands and 1061 command options, plus the 12 global options listed at the bottom of this page. It is generated from the product's own command tree, so every command and option listed here exists in this release.
Commands
| command | what it is for |
|---|---|
saphan absorb | Merges the branch a stream will land on into the stream's own branch, so the stream catches up with its base before it is merged. |
saphan accept | Records the owner's acceptance at a stream's final stop (STOP-2, after the work is proven) and then merges the stream, as one decision behind one confirmation. |
saphan account | Lists the AI vendor accounts the installation has observed through its seats' usage readings, and lets you give them readable names. |
saphan actor | Manages the people who sign decisions: this workspace's signing key and the list of enrolled actors. |
saphan ask | Asks the engine a typed question about a machine and its capabilities, from a request file that can be reviewed and replayed, and reads the receipt an answer was released under. |
saphan board | Exports the board: the workspace's recorded account of its work, with each stream's state, decision history and last commit. |
saphan bridge | Creates and maintains the bridge: the project's git repository of governing documents, orders, decisions and board that the whole team works from. |
saphan build-orchestrate | Runs a project's platform builds one at a time, in the order a build-matrix file gives, starting, health-checking and stopping any emulators each build needs, and making sure every process it started |
saphan bus | Reads the stream status files in the workspace's worktrees into the record, and reads the record's event log. |
saphan canon | Delivers the canon a seat must obey (its standing rules, governing documents and a slice of the fleet's state) to the machine the seat runs on, as a signed pack. |
saphan capture | Signs and records one spark (a short captured idea) or a session transcript, keeping the exact bytes and indexing them in the record. |
saphan ceremony | The owner's key ceremonies when a team is set up: creating the root key, which is kept only on paper, and the intermediate key used to issue machine certificates. |
saphan cert | Lets a second device trust the console's certificate, so you can sign in the Saphan Studio console from it and not only read. |
saphan certify | Runs the repository's full verification suite against the current tip of the local trunk branch, in a detached scratch worktree on this machine with your own permissions, and records the result agains |
saphan channel | Inspects and repairs the channel documents of a stream: the orders, status reports and review notes exchanged between Saphan Studio and the agents working on it, kept in the channel store. |
saphan checks | Deterministic checks that run as ordinary processes, never as a model turn, so they cost nothing in model usage and give the same answer every time. |
saphan claim | Takes an exclusive claim on a stream (one unit of work) for one actor, so two people or agents cannot pick up the same work at once. |
saphan cli | Opens Saphan Studio's interactive terminal console on the current workspace. |
saphan closure | Acts directly on a stream's closure: the cleanup job that a final owner decision (a merge, or a close without merging) starts. |
saphan config | Creates, edits and shows the installation's config file, which holds your identity and the installation's settings: ~/.saphan/etc/saphan.conf for a per-user installation, /opt/saphan/etc/saphan.conf f |
saphan confine-exec | Applies this machine's own filesystem confinement and then runs a command inside it; Saphan Studio invokes it on a remote machine to start an agent within the boundary a run was given. |
saphan console | Manages who may sign in to the web console and which passkeys may approve actions in it. |
saphan cost | Shows what a stream has cost, from the run record: the number of runs, each run with its model, its cost in US dollars, its status and its token counts (input, cached, output and reasoning), and the s |
saphan decision | Files signed decision records and governance documents into the law store, reads them back, and keeps the workspace's bridge (its shared git record) in step with them. |
saphan deny-unix-exec | Runs a command under a filter that forbids it, and everything it starts, from creating Unix-domain sockets that could reach a daemon on the host. |
saphan discover | Is meant to inspect a workspace and propose a configuration for it. |
saphan dispatch | Prepares work for an agent: on its own it renders an executor brief from a dispatch template and refuses the brief if it breaks any of the five dispatch rules. |
saphan doc | Checks record documents — orders, status returns, review returns, train orders, relays, notices and defect reports — against the format each family requires. |
saphan docs | Renders readable documents from a git checkout of your record documents: one train's chapter, or the whole body of work. |
saphan dry-run | Rehearses a command that would change the record, without making the change: saphan dry-run <command> [args...] runs the same checks the real command runs and shows what it would do, or the refusal it |
saphan egress-door | Runs one agent's egress door on a remote machine: it opens a SOCKS5 proxy on a unix socket that judges every outbound connection against the run's egress policy, runs the given command as its child, a |
saphan evidence | Parks a stream's evidence outside its worktree, places archives in the evidence store, and reads them back. |
saphan fleet | Shows the state of the fleet — streams, seats, running legs, capacity and refusals — from the record. |
saphan gate | Records one human gate decision for a stream in the signed gate log. |
saphan gates | Lists the recorded gate decisions — time, stream, gate, actor, decision, reference and detail — and checks each row's signature. |
saphan golden-delivery | Copies reference artifacts ("goldens") into a goldens directory, one subdirectory per stream, and adds a README to each stream directory that lacks one; it writes files only and commits nothing. |
saphan grammar | Prints the document formats compiled into this binary, so an agent or operator on a remote machine can read them without a source checkout, and manages the list of declared document keys. |
saphan guardrail | Inspects the model-text guardrail — the plugins that judge the text passing between an agent and its model — and prepares the owner's act that switches a stage to enforcement. |
saphan guardrail-proxy | Runs one command behind a local proxy that records, and optionally judges, the text exchanged between an AI client and its model provider. |
saphan hand | Records that a coordinating agent is handing the owner one decision to make on a stream, with the exact command to run and the output of its rehearsal. |
saphan hook | Installs Git hooks that Saphan Studio needs in a repository. |
saphan identity | Manages the signed identity store: the signed record of actors (people and their keys), OAuth client bindings, token issuers and name aliases. |
saphan infra | Places the deployment files Saphan Studio needs (container compose files, the telemetry collector configuration and a runbook) on disk, stores their secret values, and prepares the databases they serv |
saphan init | Lays out a workspace and then, with your consent, writes its verification settings and the minimum permissions Claude Code needs there. |
saphan install | Sets up this machine for Saphan Studio by running every step a new workspace needs, in order, and reporting each as already done, done now, or not done with the reason. |
saphan knowledge | Inspects the agent knowledge bundle compiled into this saphan binary: the role cards, skills, slash commands, subagents and shared guard scripts that Saphan Studio delivers to each AI assistant accoun |
saphan land | Closes a finished stream (a unit of work on its own branch) as one owner act: the stop-2 acceptance, the review decision, the merge and, if asked, the first teardown step. |
saphan laws | Reads and signs the laws manifest: the root-signed list of the standing-rule documents an installation treats as ratified, each with its SHA-256. |
saphan ledger | Shows or exports the cost ledger, the record of model calls, refusals and their cost in this workspace. |
saphan lib | Utilities for library trees, the versioned collections of manifests Saphan Studio loads. |
saphan license | Activates this installation against the Solo licensing portal and reports the state of its lease. |
saphan machine | Manages the machine registry: the signed list of hosts admitted to run work, their slots, and the seats (AI assistant accounts) placed on those slots. |
saphan memory | Carries an agent role's memory notes into the bridge (the shared coordination repository) and reads them back. |
saphan merge | Merges a gated stream's branch into its base branch, as the recorded act of the person who runs it. |
saphan mesh | Reads which admitted machines are on the network overlay (the mesh), as measured on each machine's own host, and finds overlay nodes that belong to no admitted machine. |
saphan message | Sends and reads messages between coordinating agent sessions, the "heads" holding the master, scribe or advisor role. |
saphan notice | Shows notifications the installation tried and failed to deliver. |
saphan order | Composes, signs and reads orders: the documents that tell an agent run what to do on a stream (one unit of work). |
saphan otel | Exports the installation's record metrics to an OpenTelemetry collector. |
saphan owner-block-discharge | Writes off a stream's outstanding owner-block debt, with a stated reason, when no run on that stream can ever settle it, typically because the stream is already merged or closed. |
saphan owner-block-settle | Settles a stream's owner-block debt by recording a well-formed owner block from a file, without starting a run, so the stream can be dispatched again. |
saphan person | Performs a person's own act from the command line with a FIDO2 security key: checking what the host offers, enrolling a key, and signing orders. |
saphan policy | Validates, inspects and merges drafts of the two policy document types: egress rule-sets (policy egress) and permission classes (policy grant). |
saphan pr-preflight | Runs seven checks on the current branch before you open a pull request (branch name, working-tree status, commit subjects, how far it is behind the base, submodules, a clean build and a passing scoped |
saphan prompt | Manages the prompt library: reusable prompt documents that a person picks and copies into a model. |
saphan refusal-class | Records and reads the owner's ratification of refusal classes — the named categories of reason, such as gate-integrity, for which Saphan Studio refuses an act. |
saphan refusals | Lists every refusal this binary can record, in plain language: what it means, what to do next, who has to act, and whether a retry can work. |
saphan relay | Records requests between masters — the coordinating sessions that each run a set of streams — when one master's streams cannot finish without an answer from another. |
saphan return | Brings a stream's results home from the run that worked on it — its status file into the stream's local channel, its committed branch into this workspace's repository, and for a review run the reviewe |
saphan review | Checks that an executor's completion report for a stream is structurally complete — the diff and output attached, and a well-formed close signal that matches the stream's registry entry — and, if it i |
saphan role | Starts the working environment for a role a person occupies at a terminal: master, advisor or scribe. |
saphan round | Records facts about a round — one pass of work on a stream, normally carried out by an agent run — when part of that round was done by hand. |
saphan route | Answers which tier a step is routed to under a routing policy: the first matching rule wins, otherwise the policy's default. |
saphan run | Starts one process — an AI coding agent or any executable — under a mandate and records it as a run: the model, effort, budget, time limit, working directory and permissions are fixed up front, enforc |
saphan say | Composes one validated statement for the owner — an alert, an open item, or an explicit "nothing to report" — in the owner-block format that a run's status channel carries; nothing is recorded in the |
saphan scratch | Inspects and frees the one scratch directory where Saphan Studio keeps every temporary directory it makes on a host, $HOME/.saphan/scratch, with one entry per kind, stream and run. |
saphan seat | Acts on one seat — a vendor CLI login, with its own profile directory, on an admitted machine: checking and repairing its credential, configuring its vendor settings, and issuing or ending the tokens |
saphan serve | Intended to serve the embedded web configurator. |
saphan server | Runs the projection server, which serves the installation's record over MCP (stdio and HTTP), as static HTML, and as the console at /console, reading state fresh from the record on every request. |
saphan serverd | A former command: the background daemon now runs as the separate saphan-server binary. |
saphan service | Registers Saphan Studio's background services with this machine's service supervisor so they come back after a restart. |
saphan session | Manages the sessions the installation's record knows about: conversations the console started, terminals opened in the console, and attached sessions — agent sessions running in your own terminal that |
saphan session-hook | Runs Saphan Studio's built-in hook for one event of an agent session: sessionstart, pretooluse, posttooluse, precompact or stop. |
saphan show | Prints a registered order — the instruction document a piece of agent work runs under — exactly as it was registered, read from the commit recorded with its registration. |
saphan stop2 | Closes a round of work you authored yourself, in one command, from inside that round's worktree. |
saphan store | Inspects the workspace's state store on disk: which processes hold its files, how its schema level compares with this binary's, and whether it is marked shared or scratch. |
saphan task | Intended to generate task specifications from genre manifests. |
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 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. |
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 |
saphan verify | Checks a signed instruction — a law document by path, or a registered order by reference — against the installation's trust chain (root key, actor registry, laws manifest and delegations) and prints o |
saphan verify-affected | Runs a fast, advisory check of what changed between --base and --head: the changed paths are handed to the test adapter configured under [verify.affected], which selects and runs the affected packages |
saphan verify-deploy | Verifies a deployment end to end and reports PASS only with proof for every step: it records the artifact's digest, builds, checks that the digest changed, runs the rollout, then requires the live hea |
saphan verify-stream | Runs a fixed, deterministic check of a Go stream's local worktree — go build, go vet, go test and gofmt, each step even after an earlier failure — with no language model involved, and stores the verdi |
saphan verify-union | Tests what a stream's branch does once merged: it combines the branch with the current tip of its trunk in a temporary detached worktree and runs the repository's full test suite there, then removes t |
saphan version | Prints the binary's build information: version, commit, build channel, build date and Go version. |
saphan wave | Shows the fleet's streams from the branch, gate and merge point of view. |
saphan workspace | Manages this machine's registry of the workspaces its daemon serves (workspaces.json in Saphan Studio's configuration directory), and each workspace's inventory of source repositories. |
Global options
| option | type | what it does |
|---|---|---|
--color | string | Whether output uses colour: auto (only on a terminal), always or never. |
--help-all | bool | Show every top-level command together with the global options. |
--json | bool | Print machine-readable JSON with stable field names instead of text; the same as --output-format json. |
--merged-ref | string | The branch a command treats as "already merged" when it checks whether work has landed. Defaults to each stream's own base branch. |
--output-format | string | text (the default) or json. |
--project | string | The project within the workspace to act on, when a workspace holds more than one. |
--quiet | bool | Print only the final result line; the full detail still goes to the command's log. |
--state-dir | string | The directory holding the installation's state. Defaults to .saphan/state under the workspace. |
--system | bool | Use the paths of a system-wide installation instead of a per-user one. Normally detected; this option overrides the detection. |
--text | bool | Force plain text output without colour, even on a terminal. |
--verbose | bool | Print more detail, including where each configuration value came from. |
--workspace | string | The workspace root to act on. Defaults to the nearest workspace above the current directory. |