CLI Reference

The relay-core binary provides a full-featured command-line interface for running the proxy, inspecting traffic, and managing rules, scripts, and certificates. For the full schema run relay-core --help or relay-core <command> --help.

Daemon lifecycle

One long-lived daemon owns the engine and the proxy lifecycle: the single state lives in it, it publishes $RELAY_DATA_DIR/daemon.json for clients to discover, and it serves the control API, the MCP endpoint, and the embedded Web UI. relay-core status prints the page URL. Turn the page off with --no-web or [daemon] webui = false. Every other surface — CLI, MCP bridge, Web UI, TUI — is a client of it. The proxy still starts only when a command or tool asks for it.

relay-core start      Start the daemon and the proxy (idempotent; attaches if already up)
relay-core stop       Stop the proxy only; the daemon, history and rules stay
relay-core restart    Restart the proxy
relay-core status     Daemon / proxy phase and port / MCP and Web UI URLs / last change
relay-core shutdown   Stop the proxy and the daemon (returns once the registry is clean)
relay-core config     Read, show and seed the configuration file

start is idempotent: an already-running daemon is attached to, an already-running proxy reports the port it listens on, and a taken port fails with start_failed rather than reporting success for a proxy that never bound. status also reports the last lifecycle change and who asked for it, e.g. stopped by cli:relay-core stop.

run

Run that same daemon in the foreground — not a second engine, just one that does not detach and ends when you quit. It publishes the same manifest and serves the same control API and MCP endpoint; with --ui the TUI is its client, reading the same event stream every other client reads.

relay-core run [options]

Listen & lifecycle:
  -l, --listen <ADDR>           Proxy listen address (default 127.0.0.1:8080)
      --udp-tproxy-port <PORT>   Enable UDP TPROXY on this port (Linux only)
      --transparent               Enable transparent proxy mode (macOS PF / Linux TPROXY)

TLS interception:
      --ca-cert <PATH>           CA certificate path
      --ca-key <PATH>            CA private key path (pair with --ca-cert)

Rules & scripts:
      --rules <PATH>             Load rules from file (JSON / YAML)
      --script <PATH>            Load Deno script file
      --script-watch              Watch script file for hot reload
      --script-env-allow <LIST>  Comma-separated env var names scripts may read
      --script-fetch-allow <LIST> Hosts relay.fetch may call (comma-separated; * is any host).
                                  Setting this is what enables relay.fetch, and it must be set
                                  before the script is loaded

TUI:
      --ui                        Enable interactive TUI mode
      --web                       Serve the Web UI even when the config file turned it off
      --no-web                    Do not serve the embedded Web UI
      --theme <NAME>             TUI color preset: relay, slate, high-contrast
                                  (overrides RELAY_CORE_TUI_THEME and config)

Flow recording:
      --save-stream <PATH>       Append every flow update as JSONL to this file (bodies and
                                  WebSocket messages included)

Control API and MCP:
      --api-port <PORT>          Control API / Web UI port (default 8082; an ephemeral port
                                  is used when it is taken)
      --api-bind <ADDR>          Bind address (default 127.0.0.1)
      --api-token <TOKEN>        Bearer token (the daemon generates one and publishes it in the
                                  manifest)
      --api-cors <ORIGINS>       CORS allowed origins (comma-separated)
      --mcp-port <PORT>          Also serve the MCP endpoint from this process (default 18083)

Upstream proxy:
      --upstream <URL>           Parent proxy URL (http:// or https://)
      --upstream-auth-user <U>   Username for upstream Basic auth
                                  (password: RELAYCORE_UPSTREAM_PASSWORD env)
      --upstream-bypass <LIST>   Hosts to bypass upstream
      --upstream-fail-open        Fall back to direct if upstream unreachable

See TUI for the interactive terminal UI, Proxy Modes for deployment options, and Configuration for environment variables and data directory layout.

ca

Manage the CA certificate for HTTPS interception. See Certificates for platform-specific install instructions, Windows .cer export, and CI/container setup.

relay-core ca <subcommand>

Subcommands:
  generate [--force]            Generate CA cert and key (default ~/.relay-core/)
  install                       Install CA to system trust store (macOS)
  uninstall                     Remove CA from system trust store (macOS)
  status                        Show CA paths, existence, and trust status
  export [-o PATH] [--der]      Export CA certificate
                                --der produces a binary .cer for Windows import

rules

Manage interception rules.

relay-core rules <subcommand>

Subcommands:
  validate <file>              Validate a rules file (JSON / YAML)
  print <file> [--format F]     Print rules in normalized form (json | yaml, default yaml)
  test <file> --flow <flow.json>
                                Run a sample flow through the rule set
  list [--api-url <URL>]       List rules from a running proxy via the HTTP API
                                (default http://127.0.0.1:18082)

scripts

Manage Deno-based request/response modification scripts.

relay-core scripts <subcommand>

Subcommands:
  validate <file>              Load a script into the Deno engine to check syntax
  run-once <file> --flow <f>   Execute the script once against a sample flow JSON
  init [dir]                    Scaffold an esbuild + tsconfig project (default .)
  build [entry] [-o OUT]        Bundle the entry script (default src/index.ts -> dist/bundle.js)
  dev [entry] [-o OUT]          esbuild --watch mode for local development

The init subcommand creates a starter src/index.ts and tsconfig.json. build / dev use esbuild to produce a single bundle that --script can load.

flows

Inspect captured traffic: a listing of recent flows by default, a live stream with --follow. Both read the running daemon's control API, discovered from its manifest — there is no URL to configure by hand.

relay-core flows [options]

Connection:
      --api-url <URL>           Control API base URL (discovered from the daemon manifest when
                                omitted)
      --follow                   Stream new flows; filters do not apply to a live stream, so the
                                 two cannot be combined

Listing filters:
      --host <HOST>             Substring match on host
      --path <PATH>             Substring match on path
      --method <METHOD>         HTTP method (GET, POST, ...)
      --status-min <N>          Minimum status code
      --status-max <N>          Maximum status code
      --has-error                Only flows with errors
      --websocket                Only WebSocket flows
      --filter <EXPR>           Filter expression (see syntax below)
      --limit <N>               Max results (1-200, default 50)

Output:
      --output <FORMAT>         table, json, jsonl (default table)

metrics

Display runtime metrics. The proxy is queried over HTTP at --proxy-url (default http://127.0.0.1:8080).

relay-core metrics [options]

      --proxy-url <URL>         Proxy metrics endpoint (default http://127.0.0.1:8080)
      --output <FORMAT>         table, json (default table)

Reported metrics include flows total / in memory / dropped, intercepts pending,
WebSocket pending messages, oldest intercept / WS message age, rule execution
errors, audit event totals and failures, and the lagged counters for both
flow and audit event channels.

For a Prometheus-formatted scrape, use the HTTP API endpoint GET /api/v1/metrics/prometheus (see HTTP API).

analyze

Analyze a traffic dump (from --save-stream) or a HAR export offline. A recorded file may hold a whole flow per line or a flow update per line — the new recording is lossless and includes incremental updates — and both are read.

relay-core analyze --file <PATH> [options]

      --file <PATH>             Path to JSONL flow dump or HAR file
      --format <FORMAT>         jsonl (default) or har
      --output <FORMAT>         table (default) or json
      --top-n <N>               Number of slow requests to show (default 10)

Prints a host histogram, method histogram, status histogram, top-N slowest
requests, and clustered error groups.

proxy

Manage transparent proxy on macOS (PF) or Linux (TPROXY). Compiled only with the transparent-macos or transparent-linux features.

relay-core proxy <subcommand>

Subcommands:
  generate [--port P] [--interface I] [-o OUT]
                                Write PF / TPROXY config to OUT (default stdout)
  load --port P [--interface I] Activate the rules (requires sudo)
  unload                        Deactivate the rules (requires sudo)
  status                        Show current rules

Environment variables

RUST_LOG                        Log filter (e.g. info, debug, trace). RELAY_LOG in the CLI help is not read
RELAY_DATA_DIR                  Data directory (default ~/.relay-core)
RELAY_CA_CERT                   CA cert path (pair with RELAY_CA_KEY)
RELAY_CA_KEY                    CA key path (pair with RELAY_CA_CERT)
RELAY_CORE_TUI_THEME            TUI preset when --theme is omitted
                                (relay, slate, high-contrast)
RELAYCORE_UPSTREAM_PASSWORD     Upstream proxy Basic auth password
                                (used with --upstream-auth-user)
RELAY_API_PORT                  Control API / Web UI port override
RELAY_MCP_PORT                  MCP endpoint port override for the daemon
RELAY_PROXY_PORT                Proxy port override
RELAY_PROXY_IDLE_TIMEOUT        Seconds without traffic before the proxy stops (0 = never)
RELAY_MCP_URL / RELAY_MCP_TOKEN Endpoint and token the MCP bridge should use directly
RELAY_MCP_NO_AUTOSTART          Set to 1 to forbid the bridge from starting a daemon

See Configuration for the full data directory layout and path precedence.