scribe-auth CLI reference

Identity service and auth administration.

scribe-auth runs the shared TLS identity service and administers users, service accounts, passwords, credentials, storage identities, repository grants, repository visibility, namespace readers, namespace administrators, and gateway delegates. It also generates private CAs and server certificates.

The auth database has one owner. Initialize it explicitly, then serve it with its original pepper file and its revision witness. Keep the pepper, the witness and credential files outside the auth data root. Remote administration requires an administrator credential file; a storage server credential, a service-account credential, or a password-issued user session cannot administer auth. migrate is the only command that upgrades an older auth data directory; serve refuses one. restore is the only way to bring back a backup.

See the authentication guide for identities and certificates, roles, TLS trust, passwords, session lifetime, rollback protection, and credential recovery.

scribe | scribe-server | scribe-ctl | scribe-gateway | scribe-runner

Reading this reference

Command synopses below come from this checkout’s built --help output. Angle brackets denote values, square brackets optional arguments, and ... repeatable arguments. [OPTIONS] includes the global options below and any command-specific options. Global options work before or after a subcommand; parent-group options also apply to their child commands. Use -- to end option parsing when passing a positional path that starts with a dash.

Run scribe-auth --help for the command list, scribe-auth COMMAND --help for command help, and scribe-auth --version for the build version. scribe-auth help COMMAND also displays command help. The command sections below cover every public action.

Help and version

-h / --help works at every command level. -V / --version is a top-level option; place it directly after the executable name.

Global options

Defaults and configuration

For remote administration, supply --admin-credential FILE: the credential file names the auth endpoint and its CA and holds the administrator's device key and credential certificate, so no other connection option is needed. The option is global but used only by administrative commands, not by offline initialization, migration, restore, certificate generation or the daemon. On Unix the file must grant nothing to group or other.

--state-dir stores pending administrative intents, and the new device key of a credentials create, before transmission. It defaults to auth-admin under the Scribe configuration root (the root scribe --config-dir / SCRIBE_CONFIG_DIR selects: ~/Library/Application Support/Scribe on macOS, %LOCALAPPDATA%\Scribe on Windows, $XDG_CONFIG_HOME/scribe or ~/.config/scribe on Linux). It is created private and may not be inside a .scribe directory. Retry an interrupted mutation with the same arguments and files; operations outcome ID queries a recorded outcome.

List commands return at most 256 rows. Use the first column of the final row as --after KEY to fetch the next page. Output is tab-separated rows in text mode and a rows array with --json; secrets are never printed.

Logging defaults to info, on stderr. SCRIBE_LOG supplies a filter; --log-filter overrides it. --log-level conflicts with --log-filter. --log-format accepts text or json. -v/--verbose selects debug, repeated twice selects trace, and conflicts with -q/--quiet. --timings independently enables phase timings and requires the default-enabled timings feature. serve --log-dir enables daily files; retention defaults to 14 and --log-keep-files must be at least 1. JSON command results are independent of diagnostic format.

--verbose and --quiet also conflict with explicit --log-level or --log-filter. Choose one verbosity/filter selection. Text diagnostics are the default; redirected output is plain and NO_COLOR=1 disables terminal colors.

Command index

• certs — Create a private CA or issue server PEM certificates
• certs init-ca — Create ca.pem and ca-key.pem in a new directory. Keep the CA key offline
• certs issue — Issue server.pem (the certificate followed by its CA) and server-key.pem using an existing Scribe CA
• init — Create an empty auth data directory and the bootstrap administrator's credential
• migrate — Upgrade an auth data directory to this build's schema (stop the service and back up the directory first). From schema 3, every token and session is replaced; accounts, passwords and grants are kept
• restore — Restore an auth backup into a new directory, revoking every credential issued before it (stop the service first)
• admin-credential — Offline break-glass recovery of auth administration (stop the service first)
• admin-credential issue — Issue a new administrator credential directly into a stopped auth data directory, for when every administrator credential is lost
• authorities — Rotate auth's internal client CAs, which only Scribe's services trust (stop the service first): list them, add a successor, retire the oldest
• authorities list — List the credential and access CAs of a stopped auth data directory: number, subject, fingerprint, expiry, and when each signs
• authorities add — Add a successor to the credential or access CA. Every service trusts it from its next start or trust refresh; it signs 15 minutes after it is added
• authorities retire — Retire the oldest credential or access CA once nothing it signed can still be used: access, an hour after its successor signs; credential, once no live credential holds one of its certificates, or with --revoke-held together with revoking those that still do
• serve — Run the auth service (TLS 1.3 with hybrid post-quantum key exchange; clients present certificates)
• visibility — Inspect or change repository visibility; public grants anonymous reads of all accepted history
• visibility get — Show repository key, visibility, and policy revision
• visibility set — Set visibility durably; requires the revision returned by get
• operations — Resolve a previously transmitted administrative operation
• operations outcome — Show the durably recorded outcome of an administrative operation id
• users — Add, list, enable, or disable user and service accounts
• users add — Create a user; set their login password with users password
• users password — Set/reset a login password and invalidate every existing user session
• users list — List users and service accounts: key, ID, name, enabled, administrator, kind (at most 256 rows; continue with --after LAST_KEY)
• users disable — Disable a user and revoke every credential they hold (enabling again revives none)
• users enable — Re-enable a disabled user
• credentials — Issue administrator, service-account, or server credentials; list or revoke all credentials
• credentials create — Issue a credential and write it to a new file: a device key generated here and the certificate auth issued for it. Auth stores only the public key's digest
• credentials list — List credential ids, kinds, subjects, labels, expiry and creation time (never keys), optionally for one user
• credentials revoke — Revoke one credential by the id shown in credentials list
• servers — Register storage-server identities and the namespace each belongs to
• servers add — Register a storage-server identity in a namespace; then issue it a credential with credentials create --server
• servers list — List registered servers (at most 256 rows; continue with --after LAST_KEY)
• servers disable — Disable a server identity and its credentials
• servers enable — Re-enable a disabled server identity
• grants — Set, revoke, or list per-repository roles (reader, writer, maintainer)
• grants set — Give a user a role on one repository (replaces any existing role)
• grants revoke — Remove a user's role on one repository
• grants list — List grants, optionally for one repository (at most 256 rows; continue with --after LAST_KEY)
• namespace-admins — Grant or revoke administration of every repository in a namespace
• namespace-admins set — Make a user administrator of every repository in a namespace (includes repository creation)
• namespace-admins revoke — Remove a user's namespace administration
• namespace-admins list — List namespace administrators (at most 256 rows; continue with --after LAST_KEY)
• namespace-readers — Grant or revoke read access to every repository in a namespace, including later ones
• namespace-readers set — Let a user or service account read every repository in a namespace, including ones created later
• namespace-readers revoke — Remove a namespace-wide reader grant; direct repository grants are unaffected
• namespace-readers list — List namespace-wide readers, optionally for one namespace (at most 256 rows; continue with --after LAST_KEY)
• delegates — Let a gateway's service account act for users in a namespace, or stop it
• delegates set — Let a service account (a gateway) present users' access certificates to storage servers of a namespace
• delegates revoke — Stop a service account acting for users in a namespace
• delegates list — List delegate grants, optionally for one namespace (at most 256 rows; continue with --after LAST_KEY)
• audit — Read administrative audit entries, paginated by the first column
• access — Show who can do what: every account with its kind and state, auth administration, namespace grants, repository roles and live credentials, one row each (account, kind, state, scope, access, detail). Reads every page; changes nothing

certs

Create a private CA or issue server PEM certificates

scribe-auth certs [OPTIONS] <COMMAND>

Subcommands: init-ca, issue.

certs init-ca

Create ca.pem and ca-key.pem in a new directory. Keep the CA key offline

scribe-auth certs init-ca [OPTIONS] --out <NEW_DIR>

Output directories must be new. Certificate lifetimes accept 1–3650 days.

certs issue

Issue server.pem (the certificate followed by its CA) and server-key.pem using an existing Scribe CA

scribe-auth certs issue [OPTIONS] --ca <DIR> --out <NEW_DIR>

Output directories must be new. Certificate lifetimes accept 1–3650 days. Provide at least one --dns or --ip; both are repeatable. DNS wildcards are not accepted. The CA must remain valid throughout the requested leaf lifetime.

init

Create an empty auth data directory and the bootstrap administrator's credential

scribe-auth init [OPTIONS] --pepper-out <FILE> --revision-file <FILE> --data-dir <DIR> --admin-credential-out <FILE> --auth <ENDPOINT> --auth-ca <FILE>

The data directory must be new or empty. The pepper, the revision witness and the administrator credential file must be new files outside the auth data root and any .scribe directory; every path is checked before anything is created. init creates the trust domain (1–64 lowercase letters, digits, ., -, _), the credential and access CAs, a new incarnation at revision 0, and the reserved admin account with a nonexpiring credential labelled bootstrap. The device key is generated here; the credential file holds it with its certificate, --auth (the address administrators reach the service at) and the --auth-ca certificate. Retain the pepper and the witness separately from database backups. Output:

initialized DIR; administrator credential saved to FILE; password pepper saved to FILE; revision witness saved to FILE

With --json: {"ok":true,"data_dir":…,"admin_credential_file":…,"pepper_file":…,"revision_file":…,"trust_domain":…}.

migrate

Upgrade an auth data directory to this build's schema (stop the service and back up the directory first). Every token and session is replaced; accounts, passwords and grants are kept

scribe-auth migrate [OPTIONS] --data-dir <DIR>

serve refuses an auth directory whose SCRIBE_AUTH marker names an older schema, with auth schema 3 is not supported by this build (supports 4); run `scribe-auth migrate` explicitly. Stop the service (the command takes the data directory's exclusive lock and fails while serve holds it), back up the directory, optionally run with --dry-run, then run it without. A real run needs --revision-file; the administrator options are needed only from schema 3, and a run from schema 3 without them is refused. Only schema 3 upgrades to 4. It keeps accounts, passwords, grants, namespace roles, visibility, storage servers (each assigned an immutable random ID) and audit rows; it removes every token, session and automation token, creates the trust domain, both client CAs and the rollback state, and writes a new admin credential (label migrated, 3650 days) to --admin-credential-out before the records commit. Afterwards people sign in again and every machine, storage server and gateway needs a new credential file. Any malformed user or server record aborts before anything is written. The pepper is not needed. Rerunning an interrupted or completed migration is safe; a rerun that finds the credential file but no converted records asks you to remove the file first. A current directory reports DIR is already at auth schema 4; nothing to do. Otherwise the output is:

DIR: auth schema 3 -> 4: N accounts kept, M servers given ids, K token and session records removed; issue new credentials

With --dry-run the line says (dry run; nothing written) and would be removed. With --json, the result is {"ok":true,"data_dir":…,"from":3,"to":4,"users":N,"servers":M,"dropped":K,"dry_run":false}. See the auth guide.

restore

Restore an auth backup into a new directory, revoking every credential issued before it (stop the service first)

scribe-auth restore [OPTIONS] --from <DIR> --data-dir <DIR> --revision-file <FILE> --admin-credential-out <FILE> --auth <ENDPOINT> --auth-ca <FILE>

The only way to bring an auth backup back: copying files over a data directory is refused at startup and by every storage server (see rollback protection). The backup must be auth schema 4 and is never modified; the target must be new or empty. The witness may be missing. restore starts a new incarnation, sets the revision past both the backup and the witness, revokes every credential that was live in the backup (server credentials only without --keep-server-credentials), writes a recovery administrator credential for admin (label restore-recovery, 30 days) to the new file before committing, records a restore audit row, and rewrites the witness. Accounts, passwords, grants and policies are kept. Output:

restored into DIR; N credentials revoked, M server credentials kept; recovery administrator credential saved to FILE. Users sign in again; issue new machine credentials.

With --json: {"ok":true,"data_dir":…,"revoked":N,"kept_server_credentials":M,"revision":R,"incarnation":…,"admin_credential_file":…,"admin_credential":ID}. The procedure is in auth backup and restore.

admin-credential

Offline break-glass recovery of auth administration (stop the service first)

scribe-auth admin-credential [OPTIONS] <COMMAND>

Subcommands: issue.

admin-credential issue

Issue a new administrator credential directly into a stopped auth data directory, for when every administrator credential is lost

scribe-auth admin-credential issue [OPTIONS] --data-dir <DIR> --user <USERNAME> --out <FILE> --auth <ENDPOINT> --auth-ca <FILE>

Run it on the auth host after stopping serve and backing up the directory; it fails while serve holds the lock. The user must already be an enabled person auth administrator (the bootstrap admin cannot be disabled). The device key is generated here and written with its certificate to the new file, which is flushed before the credential, its index rows and an admin-credential-issue-offline audit row are committed in one durable transaction; the credential is labelled offline-recovery. The key is never printed. If the run is interrupted after the file is written, the file names an unregistered credential and authenticates nothing, and a rerun refuses it: remove it and run again. Output is issued an offline administrator credential for USER; saved to FILE; credential ID; expires MS (Unix ms), or with --json {"ok":true,"data_dir":…,"user":…,"credential_file":…,"credential":…,"expires":MS}. Then start the service, issue a regular credential with credentials create, and revoke this one. See no administrator credential left.

authorities

Rotate auth's internal client CAs, which only Scribe's services trust (stop the service first): list them, add a successor, retire the oldest

scribe-auth authorities [OPTIONS] <COMMAND>

Subcommands: list, add, retire.

Each takes the stopped data directory's exclusive lock, so it fails while serve runs. Every CA auth holds is trusted (trust-bundle lists them all); one added later signs 15 minutes after it was added, by when every running storage server and gateway has refreshed its trust. In a scribe-ctl cluster, scribe-ctl renew --rotate-ca credential|access and --retire-ca run these between a drain and a start. See auth's internal CAs.

authorities list

List the credential and access CAs of a stopped auth data directory: number, subject, fingerprint, expiry, and when each signs

scribe-auth authorities list [OPTIONS] --data-dir <DIR>

$ scribe-auth authorities list --data-dir ./data/auth
credential 0000	CN=Scribe credential CA	BLAKE3:bf7f9fdc1899575176148fba69920dfbdb2d4bb9f22d28d4ac868e2e1c07580f	expires 2046-09-27	signing
access 0000	CN=Scribe access CA	BLAKE3:f91566c6ce7fc7a204afad08fe2420d23f304067169e6187e88b6e942654785c	expires 2046-09-27	signing

With --json: {"ok":true,"authorities":[{"purpose","index","subject","fingerprint","not_after_ms","activates_ms","signing"}…],"revision":null}.

authorities add

Add a successor to the credential or access CA. Every service trusts it from its next start or trust refresh; it signs 15 minutes after it is added

scribe-auth authorities add [OPTIONS] --data-dir <DIR> --purpose <PURPOSE>

One rotation at a time: it refuses while an earlier successor has not retired its predecessor. The new CA's name carries its number, and the addition is audited as authority-add-offline:

$ scribe-auth authorities add --data-dir ./data/auth --purpose access
access 0001	CN=Scribe access CA 1	BLAKE3:487306c1e92e291179643248cdeac9ac6094aa7ef491a85ffae0953f28e8c856	expires 2046-09-27	signs from 2026-09-27T22:26:37.000Z

authorities retire

Retire the oldest credential or access CA once nothing it signed can still be used: access, an hour after its successor signs; credential, once no live credential holds one of its certificates, or with --revoke-held together with revoking those that still do

scribe-auth authorities retire [OPTIONS] --data-dir <DIR> --purpose <PURPOSE> --revision-file <FILE>

It refuses, saying why and until when, while the oldest CA's certificates can still be presented: before its successor signs, for the access CA until an access certificate's lifetime (plus clock skew) after that, and for the credential CA while any enabled, unexpired credential holds a certificate it issued (named, so they can be renewed or revoked first; the bootstrap administrator credential never expires):

$ scribe-auth authorities retire --data-dir ./data/auth --purpose access --revision-file ./secrets/auth.revision
scribe-auth: the oldest access CA cannot be retired yet: its successor signs only from 2026-09-27T22:26:37.000Z; retire after that

The row is removed in the same durable transaction as a revision bump and an authority-retire-offline audit row, then the witness is rewritten (a start after an interruption between the two rewrites it). With --revoke-held, the credentials still holding one of its certificates are disabled in that same transaction, unless that would leave no live administrator credential (then it refuses). Output ends with retired; revision N and a revoked SUBJECT (KIND, until DATE) line per revoked credential (with --json, revision and revoked).

serve

Run the auth service (TLS 1.3 with hybrid post-quantum key exchange; clients present certificates)

scribe-auth serve [OPTIONS] --pepper-file <FILE> --revision-file <FILE> --data-dir <DIR> --tls-cert <FILE> --tls-key <FILE>

--pepper-file, --revision-file, --data-dir, --tls-cert, and --tls-key are required. Startup refuses a revision witness of another incarnation and a database behind its witness (restore such a database with restore); it rewrites a witness that is behind the database. Clients present their credential certificate, verified against auth's credential CAs in the TLS handshake; login, login-outcome, admin-login, admin-login-outcome and trust-bundle work without one. Only the hybrid key exchange X25519MLKEM768 is offered. Session TTL accepts 1–3650 days, administrator sign-in 1–24 hours (clients cannot ask for longer), storage workers 1–1024, and connection admission must be nonzero. A connection must finish its TLS handshake and send its complete request within 3 seconds; it may then carry further requests and is closed after 60 seconds idle. When every connection slot is taken, the oldest connection still waiting for a complete request (including an idle one between requests) is closed to admit a newcomer. See auth service limits. --runtime-dir is optional; when supplied it publishes listen, pid, and a cooperative shutdown-request path, and an existing directory must not be writable by group or other. A new session TTL or administrator sign-in lifetime does not extend credentials already issued.

visibility

Inspect or change repository visibility; public grants anonymous reads of all accepted history

scribe-auth visibility [OPTIONS] <COMMAND>

Subcommands: get, set.

visibility get

Show repository key, visibility, and policy revision

scribe-auth visibility get [OPTIONS] <REPOSITORY>

visibility set

Set visibility durably; requires the revision returned by get

scribe-auth visibility set [OPTIONS] --expected-revision <EXPECTED_REVISION> <REPOSITORY> <VISIBILITY>

This requires auth administrator credentials; it does not alter explicit grants. See public repositories.

operations

Resolve a previously transmitted administrative operation

scribe-auth operations [OPTIONS] <COMMAND>

Subcommands: outcome.

operations outcome

Show the durably recorded outcome of an administrative operation id

scribe-auth operations outcome [OPTIONS] <ID>

users

Add, list, enable, or disable user and service accounts

scribe-auth users [OPTIONS] <COMMAND>

Subcommands: add, password, list, disable, enable.

users add

Create a user; set their login password with users password

scribe-auth users add [OPTIONS] <NAME>

--service and --administrator conflict. A service account shares the username rules and ID space of users, so its name appears in grants, audit, and submit attribution. See service accounts.

users password

Set/reset a login password and invalidate every existing user session

scribe-auth users password [OPTIONS] --password-file <FILE> <NAME>

The password must contain 12–1024 UTF-8 bytes. The command chooses a new random password generation, which invalidates every session and automation credential of the user; auth refuses a change that keeps the previous generation. The password travels only as the request's secret field, never in an argument, outcome or audit row. A service account has no password and is refused.

users list

List users and service accounts: key, ID, name, enabled, administrator, kind (at most 256 rows; continue with --after LAST_KEY)

scribe-auth users list [OPTIONS]

Each row is users/<name>, immutable ID, name, enabled, administrator, and kind (person or service). Results are paginated, at most 256 rows. Pass the last row’s first column as --after KEY to continue.

users disable

Disable a user and revoke every credential they hold (enabling again revives none)

scribe-auth users disable [OPTIONS] <NAME>

The bootstrap admin cannot be disabled. Every credential of the account is revoked in the same transaction, so users enable gives the account back but no session or credential: people sign in again and machines need new credential files.

users enable

Re-enable a disabled user

scribe-auth users enable [OPTIONS] <NAME>

credentials

Issue administrator, service-account, or server credentials; list or revoke all credentials

scribe-auth credentials [OPTIONS] <COMMAND>

Subcommands: create, list, revoke.

credentials create

Issue a credential and write it to a new file: a device key generated here and the certificate auth issued for it. Auth stores only the public key's digest

scribe-auth credentials create [OPTIONS] --name <LABEL> --out <FILE> <SUBJECT>

--name and --out are required. --days accepts 1–3650 (default 90), or 1–365 with --service. SUBJECT must be an auth administrator (kind user), a service account with --service, or a registered storage identity with --server; --service and --server conflict, and --write requires --service. A service-account credential is a service-reader credential, or service-writer with --write; neither ever exceeds the account's live grants. Ordinary users obtain sessions through scribe login; a credential for a person who is not an auth administrator is refused with regular users must log in with a password.

The command generates a new device key, writes it durably into the state directory beside the pending request, and sends only the public key. When auth has registered it, the command fetches the credential certificate again and writes the credential file to --out: the auth endpoint and CA of the administrator's own credential file, or --auth and --auth-ca (the administrator's CA when only --auth is given). An interrupted run is resolved by repeating the same command: it certifies the same key and never issues a second credential. The output row is the new credential ID and the file:

0f1e2d3c4b5a69788796a5b4c3d2e1f0	./secrets/build-farm.credential

The auth service itself refuses lifetimes beyond 3650 days (365 for service accounts), a key or credential ID already registered, and an account already holding 256 live credentials (LIMIT_EXCEEDED). The private key is only ever written to the state directory and to that file.

credentials list

List credential ids, kinds, subjects, labels, expiry and creation time (never keys), optionally for one user

scribe-auth credentials list [OPTIONS]

Each row is credentials/<id>, kind (user, session, automation, automation-write, automation-maintain, automation-admin, service-reader, service-writer or server), subject (username, or server name for server), expiry (Unix milliseconds), enabled, label, key ID (the BLAKE3 digest of the public key), algorithm (p256), creation time (Unix milliseconds), parent (the automation credential a derived runner credential belongs to, otherwise empty) and password generation (sessions and automation credentials only). Web-issued credentials carry a label of the form web-api <name>: <scopes>, so the ceiling a kind grants can be read next to the scopes the web enforces. --user reads the per-account index instead of scanning every credential. Results are paginated, at most 256 rows. Pass the last row’s first column as --after KEY to continue.

credentials revoke

Revoke one credential by the id shown in credentials list

scribe-auth credentials revoke [OPTIONS] <CREDENTIAL>

The credential stays listed as disabled until a day after its expiry. Revoking an automation credential also stops every runner credential derived from it. Revoking the last live administrator credential of an enabled auth administrator is refused with the last administrator credential cannot be revoked; issue another first; issue a replacement first, or disable the account.

servers

Register storage-server identities and the namespace each belongs to

scribe-auth servers [OPTIONS] <COMMAND>

Subcommands: add, list, disable, enable.

servers add

Register a storage-server identity in a namespace; then issue it a credential with credentials create --server

scribe-auth servers add [OPTIONS] --namespace <NAMESPACE> <NAME>

Auth assigns the server an immutable random ID, which its certificates name. Then issue the server its credential file:

scribe-auth --admin-credential ./secrets/admin.credential credentials create storage-a --server --name daemon --out ./secrets/storage-a.credential --days 365

servers list

List registered servers (at most 256 rows; continue with --after LAST_KEY)

scribe-auth servers list [OPTIONS]

Each row is servers/<name>, immutable ID, name, enabled, and namespace. Results are paginated, at most 256 rows. Pass the last row’s first column as --after KEY to continue.

servers disable

Disable a server identity and its credentials

scribe-auth servers disable [OPTIONS] <NAME>

A disabled server's credentials are refused while it stays disabled; servers enable makes them usable again. To retire a credential for good, use credentials revoke.

servers enable

Re-enable a disabled server identity

scribe-auth servers enable [OPTIONS] <NAME>

grants

Set, revoke, or list per-repository roles (reader, writer, maintainer)

scribe-auth grants [OPTIONS] <COMMAND>

Subcommands: set, revoke, list.

grants set

Give a user a role on one repository (replaces any existing role)

scribe-auth grants set [OPTIONS] --role <ROLE> <USER> <REPOSITORY>

Maintainers also activate, change, or remove the locks.rules section in .scribe/config.toml on main, including through a merge. Writers can propose rules on other branches. Profile-only edits retaining the same ordered lock rules remain Writer operations; see repository configuration. See repository roles.

grants revoke

Remove a user's role on one repository

scribe-auth grants revoke [OPTIONS] <USER> <REPOSITORY>

grants list

List grants, optionally for one repository (at most 256 rows; continue with --after LAST_KEY)

scribe-auth grants list [OPTIONS]

Results are paginated, at most 256 rows. Pass the last row’s first column as --after KEY to continue.

namespace-admins

Grant or revoke administration of every repository in a namespace

scribe-auth namespace-admins [OPTIONS] <COMMAND>

Subcommands: set, revoke, list.

namespace-admins set

Make a user administrator of every repository in a namespace (includes repository creation)

scribe-auth namespace-admins set [OPTIONS] <USER> <NAMESPACE>

namespace-admins revoke

Remove a user's namespace administration

scribe-auth namespace-admins revoke [OPTIONS] <USER> <NAMESPACE>

namespace-admins list

List namespace administrators (at most 256 rows; continue with --after LAST_KEY)

scribe-auth namespace-admins list [OPTIONS]

Results are paginated, at most 256 rows. Pass the last row’s first column as --after KEY to continue.

namespace-readers

Grant or revoke read access to every repository in a namespace, including later ones

scribe-auth namespace-readers [OPTIONS] <COMMAND>

Subcommands: set, revoke, list.

A namespace reader grant gives the Reader role on every repository key in the namespace, including repositories created after the grant. It is combined with direct grants by taking the stronger role; it never grants writing or repository creation. It also allows namespace-wide reads such as the storage inventory a gateway or scribe-ctl polls (see namespace-wide operations). Users and service accounts can both hold it.

namespace-readers set

Let a user or service account read every repository in a namespace, including ones created later

scribe-auth namespace-readers set [OPTIONS] <USER> <NAMESPACE>

namespace-readers revoke

Remove a namespace-wide reader grant; direct repository grants are unaffected

scribe-auth namespace-readers revoke [OPTIONS] <USER> <NAMESPACE>

namespace-readers list

List namespace-wide readers, optionally for one namespace (at most 256 rows; continue with --after LAST_KEY)

scribe-auth namespace-readers list [OPTIONS]

Each row is namespace-readers/<namespace>/<user id> and the username. Results are paginated, at most 256 rows. Pass the last row’s first column as --after KEY to continue.

delegates

Let a gateway's service account act for users in a namespace, or stop it

scribe-auth delegates [OPTIONS] <COMMAND>

Subcommands: set, revoke, list.

A delegate grant lets a service account, normally a gateway's, present users' access certificates to the storage servers of one namespace, which then decide as if the user had connected directly. Only service accounts can hold it. A gateway also needs a namespace reader grant in the same namespace to poll inventory.

delegates set

Let a service account (a gateway) present users' access certificates to storage servers of a namespace

scribe-auth delegates set [OPTIONS] <USER> <NAMESPACE>

A person account is refused with only service accounts can delegate for users.

delegates revoke

Stop a service account acting for users in a namespace

scribe-auth delegates revoke [OPTIONS] <USER> <NAMESPACE>

Storage servers refuse the gateway's delegated requests in that namespace within the 30-second authorization lease.

delegates list

List delegate grants, optionally for one namespace (at most 256 rows; continue with --after LAST_KEY)

scribe-auth delegates list [OPTIONS]

Each row is delegates/<namespace>/<user id> and the username. Results are paginated, at most 256 rows. Pass the last row’s first column as --after KEY to continue.

audit

Read administrative audit entries, paginated by the first column

scribe-auth audit [OPTIONS]

--after takes the first column of the last audit row shown; empty starts at the beginning. Each row is audit/<sequence>, Unix milliseconds, actor user ID, command, operation ID, ok or rejected, and the request's arguments (a public key shown as key:<key ID>; passwords never appear). Besides administrative requests, logins, logouts, automation credential creation and derivation, offline administrator issuance and restore are recorded.

access

Show who can do what: every account with its kind and state, auth administration, namespace grants, repository roles and live credentials, one row each (account, kind, state, scope, access, detail). Reads every page; changes nothing

scribe-auth access [OPTIONS]

One report for a single storage server or a whole cluster: every permission lives in the auth service, whichever servers ask it. Accounts come in name order, each from its broadest access to its narrowest:

Only live credentials count: revoked, expired and storage-server credentials, and credentials of disabled accounts, are left out; a credential that never expires, like the bootstrap administrator's, says so. Anonymous read access to public repositories is not listed; check visibility get. A disabled account keeps its grants in the report, marked disabled; it can use none of them. Repositories appear by key, since auth knows them by ID alone. --user for an unknown account is refused, and lists that disagree (a grant naming no account) fail the report instead of guessing.

$ scribe-auth --admin-credential ./secrets/admin.credential access
admin	person	enabled	auth	administrator	accounts, grants and credentials
admin	person	enabled	namespace studio	administrator	every repository; creates repositories
admin	person	enabled	credential bootstrap	user	never expires
alice	person	enabled	repository studio/3c7298bdca2717e5a63f6da421538eba	maintainer
alice	person	enabled	sessions	1 signed in	latest expires 2026-10-03
old-monitor	person	disabled	-	none
scribe-gateway	service	enabled	namespace studio	reader	every repository, including later ones
scribe-gateway	service	enabled	namespace studio	delegate	presents users' access certificates (a gateway)
scribe-gateway	service	enabled	credential gateway	service-reader	expires 2027-09-26

With --json, rows holds the same six columns.

Use cases

See who can do what, and the audit trail

For an existing auth service and operator files (adjust the paths):

scribe-auth --admin-credential ./secrets/admin.credential access
scribe-auth --admin-credential ./secrets/admin.credential audit

access is the overview; users list, grants list, namespace-admins list, namespace-readers list, delegates list and credentials list are the raw lists it is built from, for scripts.

For initialization, the exact bootstrap credential location, adding users, and assigning roles, follow the authentication tutorial. The auth guide explains credential lifetimes and durable retries.

Output and exit codes

Exit 0 means success, 1 means runtime failure, and 2 means invalid CLI arguments. Long-running foreground commands report their final JSON result after shutdown.

--json selects machine-readable stdout results; diagnostics stay separate. See JSON output for schemas, help, and error behavior, and logging for filters, sinks, timing events, and build features.