CLI Reference

The relay-core-cli 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-cli --help or relay-core-cli <command> --help.

run

Start the proxy server.

relay-core-cli run [options]

Listen & lifecycle:
  -l, --listen <ADDR>           Proxy listen address (default 127.0.0.1:8080)
  -c, --control-port <PORT>     Control API port (default 8081)
      --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

TUI:
      --ui                        Enable interactive TUI mode
      --theme <NAME>             TUI color preset: relay, slate, high-contrast
                                  (overrides RELAY_CORE_TUI_THEME and config)

Console output (non-TUI):
      --output <FORMAT>          table, json, jsonl (default table)
      --save-stream <PATH>       Append every flow as JSONL to this file

REST / SSE HTTP API:
      --api-port <PORT>          Enable REST + SSE API on this port
      --api-bind <ADDR>          Bind address (default 127.0.0.1)
      --api-token <TOKEN>        Bearer token for HTTP API auth
      --api-cors <ORIGINS>       CORS allowed origins (comma-separated)

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-cli 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-cli 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-cli 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. Without flags, flows connects to the control WebSocket and prints a live stream. With any of --filter / --host / --path / --method / --status-min / --status-max / --has-error / --websocket / --limit it queries the REST API.

relay-core-cli flows [options]

Connection:
      --control-url <URL>       Control API for live stream (default http://127.0.0.1:8081)
      --api-url <URL>           REST API for search mode (default http://127.0.0.1:8082)

Search filters (require --api-port on the running proxy):
      --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)

intercept

Pause or resume live interception without restarting the proxy. Posts to the legacy control API.

relay-core-cli intercept <subcommand> [--control-url <URL>]

Subcommands:
  pause                         Stop accepting new intercept decisions
  resume                        Resume interception

Default --control-url is http://127.0.0.1:8081.

metrics

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

relay-core-cli 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

Offline analysis of a flow dump (from --save-stream) or a HAR export.

relay-core-cli 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-cli 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

RELAY_LOG                       Log filter (e.g. info, debug, trace)
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_PORT                      relay-core-probe proxy port (default 8080)
RELAY_CA_CERT / RELAY_CA_KEY    relay-core-probe CA paths
RELAY_PROBE_TRANSPORT           MCP transport: stdio (default) | sse
RELAY_PROBE_PORT                MCP SSE listen port (default 3000)
RELAY_PROBE_BIND                MCP SSE bind address (default 127.0.0.1)

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