orca-gateway CLI

Command reference for orca-gateway, the binary that runs and administers Orca AI Gateway - run, check, admin, tape, and plugins.

orca-gateway is the gateway's own binary and is separate from the ork CLI used with Agent Engine. It both runs the gateway and administers a running one.

Global flags

Flag	Environment variable	Notes
`--log-level <level>`	`ORCA_LOG`	Logging verbosity.
`--log-json`	`ORCA_LOG_JSON`	Emit structured JSON logs.

run

orca-gateway run --config /etc/orca-gateway/config.yaml
orca-gateway run --config postgres://orca@pg.svc/orca

Boots the data plane and the admin plane, and shuts down gracefully on SIGINT or SIGTERM. --config accepts a file path or a Postgres connection string, and also reads ORCA_CONFIG.

check

orca-gateway check config.yaml

Validates a config file without booting. Beyond schema checks it confirms that destination references resolve, plugin names are unique within their trait, scope keys used are declared, and strategies have the shape their mode requires. It also performs live checks where it can, such as confirming a TLS certificate exists and a vault resolves. Findings print as error, warning, or info lines, and the command exits non-zero on error.

Run this in CI on every config change.

version

orca-gateway version

Prints the version and commit. Running the binary with no arguments does the same and exits zero, which is useful as a container build sanity check.

plugins

orca-gateway plugins list --config config.yaml

Tabulates the plugin instances declared in a config file - family, name, kind, whether it is required, and its failure mode. This reads a file; it does not query a running gateway. Use orca-gateway admin plugins list for that.

admin

Talks HTTP to a running gateway's admin plane. Every subcommand accepts:

Flag	Environment variable	Default
`--gateway-url <url>`	`ORCA_GATEWAY_ADMIN_URL`	`http://localhost:9099`
`--actor <name>`	`ORCA_GATEWAY_ACTOR`	`$USER`, else `admin-cli`

--actor is sent as an X-Orca-Actor header on writes and recorded with the change.

orca-gateway admin destinations   list | get <name> | put <name> --file <f> | delete <name>
orca-gateway admin routes         list | get <name> | put <name> --file <f> | delete <name>
orca-gateway admin vaults         list | get <name> | put <name> --file <f> | delete <name>
orca-gateway admin rate-limits    list | get <name> | put <name> [--position <n>] --file <f> | delete <name>
orca-gateway admin plugins        list | get <name> | put <name> --family <family> --file <f> | delete <name>
orca-gateway admin config         get | validate --file <f>
orca-gateway admin import-yaml    <file>

Plugin writes name the family slot: guardrails, audit_sinks, usage_sinks, trace_exporters, signers, authorizers, rate_limiter, or cache.

import-yaml reads a config file and issues a write for every resource in it, which is the usual way to move a file-based deployment onto the control plane.

Writes require a Postgres-backed gateway. Against a file-backed gateway the admin surface is read-only, because the file is the source of truth. A successful write persists a new active revision but does not rebuild the running data plane; restart or roll the gateway to apply it. There is also no admin config rollback subcommand; see Admin API for how to roll a revision back.

tape

orca-gateway tape verify <path> [--signer-key <pem>] [--signer-id <id>]
orca-gateway tape replay <tape-id> --target <name> --path <dir> [--signer-key <pem>] [--signer-id <id>]

verify accepts a tape file or a directory of them. Without --signer-key it runs in accept-any-signer mode, checking framing and chain integrity but not the Ed25519 signature - useful for an operational corruption check that should not require the production key. --signer-id defaults to local.

replay resolves a tape id under --path, verifies it, and prints the recorded request and response.

replay does not re-issue the call. --target is accepted but the command prints what the tape recorded rather than dispatching a live request.

See Signed tapes for what a tape contains.