# `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](/docs/gateway-usage.md) for TLS configuration, placement, inventory,
and operational limits, or the [cluster guide](/docs/cluster-usage.md) to supervise it
with `scribe-ctl`.

[scribe](/docs/reference/cli/scribe.md) | [scribe-server](/docs/reference/cli/scribe-server.md) | [scribe-auth](/docs/reference/cli/scribe-auth.md) | [scribe-ctl](/docs/reference/cli/scribe-ctl.md) | [scribe-runner](/docs/reference/cli/scribe-runner.md)

## 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](/docs/gateway-usage.md#tls-configuration), 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](/docs/gateway-usage.md#identity-and-delegation)
in every namespace it fronts. The optional
[`[limits]` table](/docs/gateway-usage.md#admission-limits) 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](/docs/reference/cli/scribe-gateway.md#example) — Print a local plaintext example; no auth or gateway is required by standalone servers
- [init](/docs/reference/cli/scribe-gateway.md#init) — Explicitly initialize an empty gateway routing data root
- [serve](/docs/reference/cli/scribe-gateway.md#serve) — Poll configured instances and serve the standard Scribe client protocol
- [status](/docs/reference/cli/scribe-gateway.md#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

```sh
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](/docs/tutorials/03-add-gateway.md)
(by hand: [bare metal, stage 3](/docs/manual/bare-metal.md#3-add-a-gateway)).
The [gateway guide](/docs/gateway-usage.md) 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](/docs/json-output.md) for schemas, help, and error behavior, and
[logging](/docs/logging.md) for filters, sinks, timing events, and build features.