--- title: "CLI" subtitle: "Every respan-gateway command and flag, with an example of each." --- ```text respan-gateway [OPTIONS] [COMMAND] ``` With no command, `respan-gateway` serves. `respan-gateway --help` prints the same list, and `respan-gateway --help` the flags of one command. | Command | What it does | | --- | --- | | [`serve`](#serve) | Serve the gateway. The default. | | [`init`](#init) | Write a commented starter `gateway.toml`. | | [`check`](#check) | Check the config, print what it serves, and exit. | | [`models`](#models) | List every provider's models and exit. | | [`mcp`](#mcp) | List the MCP servers, or log in to one. | | [`proxy`](#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 ` | `RESPAN_CONFIG` | The config file. Default: `gateway.toml`, then providers from the environment. | | `--listen ` | `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 ` | `RESPAN_LOG` | How requests are logged to stderr, in place of the config's: `text`, `json` or `off`. | | `--color ` | `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](/docs/oss-gateway/config#environment-variables) for every variable. ```bash 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. ```bash 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](/docs/oss-gateway/config#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 ` | Where to write it. Default: `gateway.toml`. | | `--force` | Replace the file if it exists. Without it, `init` refuses to overwrite. | | `-p`, `--provider ` | 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. | ```bash 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. | ```bash 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. ```bash respan-gateway models ``` ## mcp With no subcommand, lists the MCP servers in `[tools.]` and whether the gateway can authenticate to each. ```bash respan-gateway mcp ``` ### mcp login ```text respan-gateway mcp login ``` 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/.json`. The server's config uses it with `auth = "login"`. On a headless machine, paste the callback address back when asked. ```bash 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 ` | 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`. ```bash respan-gateway proxy --anthropic # in another shell ANTHROPIC_BASE_URL=http://127.0.0.1:8080 claude ``` ```bash respan-gateway proxy --openai ``` Point Codex's OpenAI base URL at `http://127.0.0.1:8080/v1`. The proxy relays to the same vendor only. It does not route Claude Code to other vendors' models.