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
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 you declare so the console can show their turns. An attached session is only a declaration: nothing is started, and its turns are read, read-only, from the vendor's own transcript file inside the reading seat's profile directory.
⚠ --user and --config-dir select; they do not authenticate. Anyone who can run saphan against this workspace can name any console user and any absolute directory, so the boundary that protects sessions and transcripts is file-system access to the workspace's state directory and to each profile directory.
saphan session attach
Declares a session running in your own terminal, recording which stream it serves, which vendor wrote it, and the one transcript file the console may read. The transcript must lie inside the profile directory given by --config-dir (or this process's own), and must already exist, or the declaration is refused and nothing is written. --session-id, --stream and --workdir are required. Run it once per session, at its start.
| flag | type | default | what it does |
|---|---|---|---|
--backend | string | Which vendor wrote the transcript: claude-code or codex. | |
--config-dir | string | The seat's profile directory, as an absolute path; defaults to this process's CLAUDE_CONFIG_DIR or CODEX_HOME. | |
--name | string | An optional name for the session, shown on its card in the console. | |
--role | string | The role this session works as, which decides the console screen it appears on; without it the session appears on every screen. | |
--session-id | string | The vendor's own id for this session. | |
--stream | string | The stream this session serves. | |
--user | string | The console user this session belongs to; defaults to the provisioned console administrator. | |
--workdir | string | The session's working directory, as an absolute path. |
saphan session census
Counts the kinds of lines in a vendor session file and reports how many are read as turns and, by name, which kinds were not. It reads the file only and writes nothing.
| flag | type | default | what it does |
|---|---|---|---|
--backend | string | Which reader to measure with: claude-code or codex. | |
--path | string | The vendor's session file. |
saphan session close
Marks a terminal or attached session as closed, removing it from the console's active sessions; a closed session is final and is never resumed. Console conversations are ended by the console itself and are refused here, as are unknown ids, sessions recorded under a user other than --user and sessions already closed.
| flag | type | default | what it does |
|---|---|---|---|
--reason | string | closed by the operator | Why the session ended, as it should appear in the record; defaults to closed by the operator. |
--session-id | string | The session to close; saphan session list shows the ids. | |
--user | string | The console user; defaults to the provisioned console administrator. |
saphan session list
Lists every session that is not closed, of every kind, for one console user. It never lists all users at once.
| flag | type | default | what it does |
|---|---|---|---|
--user | string | The console user; defaults to the provisioned console administrator. |
saphan session turns
Prints the newest turns of an attached session from the transcript its record names, read-only. The read is confined to the reading seat's own profile directory (--config-dir, or this process's own), never to a directory taken from the record; both paths are resolved through symbolic links before they are compared. A session recorded under a user other than --user is refused. The console uses the same read.
| flag | type | default | what it does |
|---|---|---|---|
--config-dir | string | The directory the read is confined to, as an absolute path; defaults to this process's CLAUDE_CONFIG_DIR or CODEX_HOME. | |
--max | int | 20 | How many of the newest turns to print; defaults to 20. |
--session-id | string | The attached session to read. | |
--user | string | The console user; defaults to the provisioned console administrator. |
Global options apply to every command — see Every command.