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
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 serve. Starting containers other than the local CouchDB is left to you; creating the databases inside a CouchDB node you point Saphan Studio at is done by saphan infra databases.
saphan infra couchdb-admin
Writes Saphan Studio's CouchDB administrator, taken from the credentials file, into saphan-admin.ini in the configuration directory of a CouchDB installed as a package, so the database and Saphan Studio use the same account. If no administrator is stored yet, it asks for one on the terminal and saves it to the credentials file first. ⚠ The password sits in that file in plain text until CouchDB starts and replaces it with its hash, so start or restart CouchDB right afterwards.
| flag | type | default | what it does |
|---|---|---|---|
--dir | string | CouchDB's local.d configuration directory, when it is not the package's default ($(brew --prefix)/etc/local.d for Homebrew, /opt/couchdb/etc/local.d otherwise). | |
--for | string | How CouchDB was installed: brew, deb or rpm (the latter two write through sudo, owned by the couchdb user); required. |
saphan infra credentials
Asks on the terminal for each value the compose files need for the services you name, one named question at a time, and writes them to substrate.env beside them with mode 0600; pressing Enter keeps a value already set. Passwords are never echoed or printed back; names are shown. It needs a terminal: in a script it refuses and you fill the file by hand. CouchDB's administrator is not asked here; saphan infra up couchdb handles it.
| flag | type | default | what it does |
|---|---|---|---|
--dir | string | The directory holding the compose files; defaults to the installation's docker directory. | |
--include | stringSlice | The services this deployment runs besides CouchDB: any of postgres, keycloak and otel; with none named there is nothing to ask and the command refuses. |
saphan infra databases
Creates the databases Saphan Studio needs on the CouchDB node named by channel.base_url (or evidence.base_url) in your configuration, with their access rules: the system databases, the law and working-material databases always, and the record and telemetry databases only where configured. It also defines and builds the index the working-material reads use. Databases that already exist are left alone and reported; nothing is dropped and no container is started. ⚠ With no CouchDB credential configured, the requests are sent unauthenticated (it says so).
| flag | type | default | what it does |
|---|---|---|---|
--n | int | 1 | Replicas per shard; fixed when a database is created and cannot be changed later. |
--q | int | 2 | Shards per database; fixed when a database is created and cannot be changed later. |
--record-reader | bool | false | Also names and write-protects the record database and creates a read-only account for it, so the start check can prove that only Saphan Studio can write there; the generated password goes only to the credentials file, and the record database name and reader credential name are written into your configuration file. |
saphan infra studio
Runs the Studio server as containers from the compose project that saphan infra write placed: first start, upgrade to a new image, and roll back. Every image is given by digest; a tag is refused.
saphan infra studio install-couch-admin
Installs CouchDB's administrator settings file into its configuration volume, replacing a rotated one. The Studio compose project runs it on every start; you do not type it.
| flag | type | default | what it does |
|---|---|---|---|
--dir | string | CouchDB's configuration directory (local.d) on its configuration volume. | |
--from | string | The administrator settings file to install (the mounted secret). | |
--gid | int | 5984 | The group that owns the installed files; defaults to 5984. |
--uid | int | 5984 | The user that owns the installed files; defaults to 5984. |
saphan infra studio rollback
Returns the Studio containers to the image digest recorded before the last upgrade.
| flag | type | default | what it does |
|---|---|---|---|
--dir | string | The deployment directory; defaults to the installation's docker directory. | |
--runtime | string | docker or podman; defaults to Docker if it is installed, otherwise Podman. |
saphan infra studio sync-credentials
Copies the CouchDB administrator and cookie-secret entries from one credentials file into another when they differ, keeping every other entry and the file's owner and mode. The Studio compose project runs it inside itself; you do not type it.
| flag | type | default | what it does |
|---|---|---|---|
--from | string | The credentials file to read the entries from (the mounted secret). | |
--to | string | The credentials file to update (the copy on the home volume). |
saphan infra studio up
Starts the Studio containers. The first start needs the Studio and CouchDB image digests; later starts reuse the recorded ones.
| flag | type | default | what it does |
|---|---|---|---|
--couchdb-image | string | The CouchDB image as <repository>@sha256:<digest>; needed on the first start. | |
--dir | string | The deployment directory; defaults to the installation's docker directory. | |
--image | string | The Studio server image as <repository>@sha256:<digest>; needed on the first start. | |
--rotated-credentials | bool | false | After changing the CouchDB administrator in the credentials file: recreate CouchDB so it reads the new one, then start the rest. |
--runtime | string | docker or podman; defaults to Docker if it is installed, otherwise Podman. |
saphan infra studio upgrade
Moves the Studio containers to a new image digest on the same volumes: it records the new and the previous digest, runs the store migration with the new image while the old containers still serve, then switches the containers. A failure at either step is reported with rollback as the next step and is not undone for you.
| flag | type | default | what it does |
|---|---|---|---|
--dir | string | The deployment directory; defaults to the installation's docker directory. | |
--image | string | The new Studio server image as <repository>@sha256:<digest>. | |
--runtime | string | docker or podman; defaults to Docker if it is installed, otherwise Podman. |
saphan infra up
Starts one local service container. couchdb starts the database with its administrator taken from the credentials file, so Saphan Studio and the database cannot disagree; if none is stored it asks on the terminal and saves it, and a missing cookie secret is generated and saved. gitea starts the bundled git server, pinned by image digest, with its data on named volumes, its generated administrator password saved once under the installation's docker/secrets directory, and its listen address taken from forge.bundled_listen (loopback only by default). Both run docker compose up -d (or Podman), using sudo on Linux only when the Docker socket is not open to your account, and pass values through a temporary 0600 file that is removed afterwards. Run saphan infra write first.
| flag | type | default | what it does |
|---|---|---|---|
--dir | string | The deployment directory; defaults to the installation's docker directory. | |
--image | string | For gitea only: a digest-pinned image reference, for a build that ships without a pinned one. | |
--listen | string | For gitea only: the host:port to publish on, instead of forge.bundled_listen. | |
--project | string | For gitea only: the compose project name; defaults to compose's own, taken from the directory. | |
--root-url | string | For gitea only: the public HTTPS address, when it is served through a TLS reverse proxy. | |
--runtime | string | docker or podman; defaults to Docker if it is installed, otherwise Podman. |
saphan infra write
Writes the deployment files and their empty data directories into a directory and prints the commands to bring them up, with absolute paths. Existing files are not overwritten unless you pass --force, and the environment file substrate.env is created with mode 0600 only if absent, listing each value it needs as a commented line.
| flag | type | default | what it does |
|---|---|---|---|
--dir | string | The directory to write into; defaults to the installation's docker directory. | |
--force | bool | false | ⚠ Overwrites deployment files that already exist, discarding any edits you made to them; the environment file holding your secret values is never overwritten. |
Global options apply to every command — see Every command.
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 init
Lays out a workspace and then, with your consent, writes its verification settings and the minimum permissions Claude Code needs there.