CLI

Every respan-gateway command and flag, with an example of each.


respan-gateway [OPTIONS] [COMMAND]

With no command, respan-gateway serves. respan-gateway --help prints the same list, and respan-gateway <command> --help the flags of one command.

Command	What it does
`serve`	Serve the gateway. The default.
`init`	Write a commented starter `gateway.toml`.
`check`	Check the config, print what it serves, and exit.
`models`	List every provider’s models and exit.
`mcp`	List the MCP servers, or log in to one.
`proxy`	Relay one vendor’s whole API with each client’s own credentials.

Global options

These work with every command.

Flag	Variable	What it does
`-c`, `--config <FILE>`	`RESPAN_CONFIG`	The config file. Default: `gateway.toml`, then providers from the environment.
`--listen <ADDR>`	`RESPAN_LISTEN`	Where to listen, in place of the config’s: `127.0.0.1:8080`, `localhost:8080` or `8080`. Beyond loopback, client keys are required.
`--log <FORMAT>`	`RESPAN_LOG`	How requests are logged to stderr, in place of the config’s: `text`, `json` or `off`.
`--color <WHEN>`	`RESPAN_COLOR`	Color in terminal output: `auto` (default), `always` or `never`. `auto` respects `NO_COLOR` and redirected output.
`--watch`		While serving, reload the config file when it changes, checked every 2 seconds.
`-h`, `--help`		Print help.
`-V`, `--version`		Print the version.

Settings can also come from the nearest .env file in the current directory or its parents. See Config file for every variable.


respan-gateway --listen 0.0.0.0:8080 --log json --watch
respan-gateway --version

serve

Serves ./gateway.toml, the file named by --config, or, with neither, a provider for each vendor key in the environment. Prints the providers, MCP servers, endpoints and the web UI’s URL, then serves until stopped.


export OPENAI_API_KEY=sk-...
respan-gateway

It refuses to start on a non-loopback address without client keys. SIGHUP, POST /ui/api/reload and --watch reload the config; see Reloading. Before it listens, it reads each provider’s model list, so the first requests are routed and priced by them.

init

Writes a commented starter config. Every vendor whose key is in the environment is enabled in it.

Flag	What it does
`-o`, `--output <FILE>`	Where to write it. Default: `gateway.toml`.
`--force`	Replace the file if it exists. Without it, `init` refuses to overwrite.
`-p`, `--provider <VENDOR[=KEY]>`	Enable a vendor too, its key read from its variable (`-p groq` writes `env:GROQ_API_KEY`). `VENDOR=env:NAME` reads another variable, and `VENDOR=KEY` writes the key itself into the file. Repeat for several vendors.
`--client-key`	Generate a client key (`sk-gw-...`), write it into `client_keys`, and print it once. A gateway beyond localhost needs one.


respan-gateway init
respan-gateway init -p groq -p anthropic --client-key
respan-gateway init -o staging.toml --force

A file that holds a key (--client-key, or VENDOR=KEY) is written readable by its owner only.

check

Loads the config, prints what it serves (listen address, providers, MCP servers, endpoints, defaults, routes, auth, web UI and log), and exits. Exits with status 1 if the config is invalid.

Flag	What it does
`--online`	Also make one call to each provider with its key, listing its models, and say whether it is reachable, refuses the key, or is unreachable. Also lists the tool loop’s tools. Exits with status 1 unless every provider is reachable.


respan-gateway check
respan-gateway check -c my.toml --online

models

Lists the models of every provider, as GET /v1/models does, as a table of provider, kind and model, then exits. A provider whose list can’t be read is reported as a warning.


respan-gateway models

mcp

With no subcommand, lists the MCP servers in [tools.<name>] and whether the gateway can authenticate to each.


respan-gateway mcp


respan-gateway mcp login <NAME>

Logs in to an HTTP MCP server that needs a person to approve it once, with a device code or in a browser, and saves the login beside the config in .respan/mcp/<name>.json. The server’s config uses it with auth = "login". On a headless machine, paste the callback address back when asked.


respan-gateway mcp login linear

proxy

Relays one vendor’s whole API, byte for byte, with each client’s own credentials. It needs no config file and no keys of its own: the client’s key goes to the vendor. Use it to put the gateway in front of Claude Code or Codex, so their traffic shows in the request log and web UI.

Flag	What it does
`--anthropic`	Relay to Anthropic.
`--openai`	Relay to OpenAI.
`--url <URL>`	The vendor’s base URL, in place of its public one.
`--check`	Print the proxy’s configuration and exit.

One of --anthropic or --openai is required. proxy can’t be used with --config.


respan-gateway proxy --anthropic
# in another shell
ANTHROPIC_BASE_URL=http://127.0.0.1:8080 claude

The proxy relays to the same vendor only. It does not route Claude Code to other vendors’ models.