scribe-gateway CLI reference

Repository routing gateway.

scribe-gateway presents one Scribe endpoint backed by existing storage instances. It discovers repositories, routes requests, streams object transfers, and chooses placement for new repositories. Backend storage remains authoritative. It does not start storage services, replicate objects, or relocate repositories.

The routing data root has one owner. Initialize it explicitly before serving. Instance membership comes from TOML at startup. See the gateway guide for TLS configuration, placement, inventory, and operational limits, or the cluster guide to supervise it with scribe-ctl.

scribe | scribe-server | scribe-auth | scribe-ctl | 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-gateway --help for the command list, scribe-gateway COMMAND --help for command help, and scribe-gateway --version for the build version. scribe-gateway 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

Argument or option	Meaning
`--json`	Emit JSON command results on stdout. Diagnostics remain on stderr
`--config <CONFIG>`	Gateway TOML; relative paths resolve beside this file [default: scribe-gateway.toml]
`--timings`	Report phase timings to stderr (requires the timings Cargo feature)
`--log-format <LOG_FORMAT>`	Diagnostic format: text or json
`--log-level <LOG_LEVEL>`	Diagnostic level: off, error, warn, info, debug, trace

Defaults and configuration

--config defaults to scribe-gateway.toml in the current working directory. Paths inside TOML resolve beside that file. example prints a template without loading configuration. Listener, backend, TLS, admission, and placement settings come from gateway TOML, not command flags. A TLS gateway's [tls] table names its certificate, key, and credential, the credential file of the gateway's service account, which needs namespace reader and delegate grants in every namespace it fronts. The optional [limits] table bounds connections. There is no credential flag or environment variable.

Logging defaults to info, on stderr. --log-level accepts off, error, warn, info, debug, or trace; SCRIBE_LOG also supplies a target filter. --log-format accepts text or json. There are no --log-filter, verbose, or quiet switches. --timings requires the default-enabled timings feature. --json controls command results independently of diagnostics.

Command index

example — Print a local plaintext example; no auth or gateway is required by standalone servers
init — Explicitly initialize an empty gateway routing data root
serve — Poll configured instances and serve the standard Scribe client protocol
status — Read the last inventory snapshot; never starts or mutates any service

example

Print a local plaintext example; no auth or gateway is required by standalone servers

text

scribe-gateway example [OPTIONS]

No command-specific options; global and parent-group options still apply.

init

Explicitly initialize an empty gateway routing data root

text

scribe-gateway init [OPTIONS]

No command-specific options; global and parent-group options still apply.

serve

Poll configured instances and serve the standard Scribe client protocol

text

scribe-gateway serve [OPTIONS]

Argument or option	Meaning
`--runtime-dir <RUNTIME_DIR>`	Private readiness and cooperative shutdown directory, for supervisors

Runs in the foreground. Stop with Ctrl-C or the configured runtime directory’s shutdown-request file. --runtime-dir publishes readiness files when supplied. Restart to change configured instance membership or to load a replaced credential file. On a TLS gateway, client certificates are refused until the first fetch of auth's access CAs succeeds. With --json, the final result is emitted after shutdown.

status

Read the last inventory snapshot; never starts or mutates any service

text

scribe-gateway status [OPTIONS]

No command-specific options; global and parent-group options still apply.

Reads the last local inventory snapshot without probing backends. After shutdown the snapshot is labeled stopped. JSON includes backend health and observations, not a fresh network check.

Use cases

Inspect the last backend inventory

scribe-gateway --config ./scribe-gateway.toml status --json

This reads the local snapshot; it does not probe backends. For a working two-storage TLS setup and client handover, follow the scaling tutorial (by hand: bare metal, stage 3). The gateway guide describes placement rules and failure behavior.

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.