CLI 参考

relay-core 提供功能完整的命令行界面，用于运行代理、检查流量、管理规则、脚本与证书。完整参数请运行 relay-core --help 或 relay-core <command> --help。

守护进程生命周期

一个常驻守护进程独占引擎与代理生命周期：唯一的状态在它手里，它写 $RELAY_DATA_DIR/daemon.json 供其他客户端发现，并同时服务控制 API、MCP 端点与内嵌 Web UI。relay-core status 会打印页面地址。用 --no-web 或 [daemon] webui = false 关掉页面。其余界面（CLI、MCP 桥、Web UI、TUI）都是它的客户端。代理仍然只在命令或工具要求时才启动。

relay-core start      启动守护进程与代理（幂等；已在运行则接入并回报端口）
relay-core stop       只停代理；守护进程、历史与规则保留
relay-core restart    重启代理
relay-core status     守护进程 / 代理相位与端口 / MCP 与 Web UI 地址 / 最近一次变更
relay-core shutdown   停代理并退出守护进程（注册表清空后才返回）
relay-core config     读取、查看与生成配置文件

start 是幂等的：守护进程已在跑就接入，代理已在跑就回报它监听的端口，端口被占用则以 start_failed 失败，而不是报一个从未 listen 的成功。status 还会给出最近一次生命周期变更及其来源，例如 stopped by cli:relay-core stop。

run

在前台运行这个守护进程——与 start 拉起的是同一个守护进程，只是不脱离终端、退出即结束。它写同一份清单、服务同一个控制 API 与 MCP 端点；--ui 的 TUI 是它的客户端，读的是其他客户端读到的那条事件流。

relay-core run [options]

监听与生命周期：
  -l, --listen <ADDR>           代理监听地址（默认 127.0.0.1:8080）
      --udp-tproxy-port <PORT>   启用 UDP TPROXY（仅 Linux）
      --transparent               启用透明代理模式（macOS PF / Linux TPROXY）

TLS 拦截：
      --ca-cert <PATH>           CA 证书路径
      --ca-key <PATH>            CA 私钥路径（须与 --ca-cert 成对）

规则与脚本：
      --rules <PATH>             从文件加载规则（JSON / YAML）
      --script <PATH>            加载 Deno 脚本文件
      --script-watch              监听脚本变更自动重载
      --script-env-allow <LIST>  脚本可读取的环境变量名（逗号分隔）
      --script-fetch-allow <LIST> 允许 relay.fetch 的主机（逗号分隔；* 为任意主机）。
                                  设置此项才会启用 relay.fetch，且须在加载脚本之前

TUI：
      --ui                        启用 TUI 交互界面
      --web                       配置文件关掉页面时仍提供 Web UI
      --no-web                    不提供内嵌 Web UI
      --theme <NAME>             TUI 配色：relay、slate、high-contrast
                                  （覆盖 RELAY_CORE_TUI_THEME 与 config）

流量录制：
      --save-stream <PATH>       将每个流量更新以 JSONL 追加到该文件（含 body / WS 增量）

控制 API 与 MCP：
      --api-port <PORT>          控制 API / Web UI 端口（默认 8082，被占则回落到临时端口）
      --api-bind <ADDR>          绑定地址（默认 127.0.0.1）
      --api-token <TOKEN>        Bearer 令牌（守护进程默认自动生成并写入清单）
      --api-cors <ORIGINS>       CORS 允许源（逗号分隔）
      --mcp-port <PORT>          同时在本进程内服务 MCP 端点（默认 18083）

上游代理：
      --upstream <URL>           上级代理 URL（http:// 或 https://）
      --upstream-auth-user <U>   上级代理 Basic 认证用户名
                                  （密码：RELAYCORE_UPSTREAM_PASSWORD 环境变量）
      --upstream-bypass <LIST>   绕过上级的主机列表
      --upstream-fail-open        上级不可达时回落到直连

交互界面详见 TUI，部署模式详见代理模式，环境变量与数据目录布局见配置。

ca

管理 HTTPS 拦截所用 CA 证书。各平台安装步骤、Windows .cer 导出、CI/容器环境使用见证书与 HTTPS 拦截。

relay-core ca <subcommand>

子命令：
  generate [--force]            生成 CA 证书与私钥（默认 ~/.relay-core/）
  install                       将 CA 安装到系统信任库（macOS）
  uninstall                     从系统信任库移除 CA（macOS）
  status                        显示 CA 路径、存在性与信任状态
  export [-o PATH] [--der]      导出 CA 证书
                                --der 输出 Windows .cer 适用的二进制格式

rules

管理拦截规则。

relay-core rules <subcommand>

子命令：
  validate <file>              校验规则文件（JSON / YAML）
  print <file> [--format F]     以规范化格式打印（json | yaml，默认 yaml）
  test <file> --flow <flow.json>
                                用样本流量测试规则
  list [--api-url <URL>]       通过 HTTP API 列出运行中代理的规则
                                （默认 http://127.0.0.1:18082）

scripts

管理基于 Deno 的请求/响应修改脚本。

relay-core scripts <subcommand>

子命令：
  validate <file>              将脚本加载到 Deno 引擎以检查语法
  run-once <file> --flow <f>   对样本流量 JSON 单次执行脚本
  init [dir]                    初始化 esbuild + tsconfig 项目（默认 .）
  build [entry] [-o OUT]        打包入口脚本（默认 src/index.ts -> dist/bundle.js）
  dev [entry] [-o OUT]          esbuild --watch 模式，用于本地开发

init 子命令会创建入门用的 src/index.ts 与 tsconfig.json。build / dev 使用 esbuild 打成单文件 bundle，再由 --script 加载。

flows

查看已捕获流量：默认列出最近的流量，加 --follow 则实时跟随。两者都读运行中守护进程的控制 API，地址由清单自动发现，不需要手工配置 URL。

relay-core flows [options]

连接：
      --api-url <URL>           控制 API 基址（省略时从守护进程清单发现）
      --follow                   实时跟随新流量；过滤器不适用于实时流，二者不能同时使用

列表条件：
      --host <HOST>             主机名子串匹配
      --path <PATH>             路径子串匹配
      --method <METHOD>         HTTP 方法（GET、POST、...）
      --status-min <N>          最小状态码
      --status-max <N>          最大状态码
      --has-error                仅含错误的流量
      --websocket                仅 WebSocket 流量
      --filter <EXPR>           过滤表达式（见下方语法）
      --limit <N>               最大条数（1-200，默认 50）

输出：
      --output <FORMAT>         table、json、jsonl（默认 table）

过滤表达式语法同 TUI 过滤栏，例如 host:api method:POST status:>=400。

metrics

查看运行时指标。代理通过 HTTP 在 --proxy-url 暴露指标端点（默认 http://127.0.0.1:8080）。

relay-core metrics [options]

      --proxy-url <URL>         代理指标端点（默认 http://127.0.0.1:8080）
      --output <FORMAT>         table、json（默认 table）

输出指标包括：流量总数 / 内存中 / 已丢弃、未决拦截数、WebSocket 未决消息数、
最旧拦截 / WS 消息年龄、规则执行错误、审计事件总数与失败数，以及流量与
审计事件通道的 lagged 计数。

Prometheus 文本格式请使用 HTTP API 端点 GET /api/v1/metrics/prometheus（见 HTTP API）。

analyze

对流量 dump（来自 --save-stream）或 HAR 导出进行离线分析。录制文件每行可能是一个完整 Flow，也可能是一条 FlowUpdate（新格式无损记录增量），两种都能读。

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

      --file <PATH>             JSONL 流量 dump 或 HAR 文件路径
      --format <FORMAT>         jsonl（默认）或 har
      --output <FORMAT>         table（默认）或 json
      --top-n <N>               显示前 N 个最慢请求（默认 10）

输出主机直方图、方法直方图、状态直方图、前 N 个最慢请求、按错误聚类的分组。

proxy

在 macOS（PF）或 Linux（TPROXY）上管理透明代理。仅在启用 transparent-macos / transparent-linux 特性时编译。

relay-core proxy <subcommand>

子命令：
  generate [--port P] [--interface I] [-o OUT]
                                将 PF / TPROXY 配置写入 OUT（默认 stdout）
  load --port P [--interface I] 激活规则（需要 sudo）
  unload                        关闭规则（需要 sudo）
  status                        显示当前规则

环境变量

RUST_LOG                        日志过滤（如 info、debug、trace）。帮助文本里的 RELAY_LOG 目前不会被读取
RELAY_DATA_DIR                  数据目录（默认 ~/.relay-core）
RELAY_CA_CERT                   CA 证书路径（与 RELAY_CA_KEY 成对）
RELAY_CA_KEY                    CA 私钥路径（与 RELAY_CA_CERT 成对）
RELAY_CORE_TUI_THEME            TUI 主题（relay、slate、high-contrast），
                                在 --theme 缺省时使用
RELAYCORE_UPSTREAM_PASSWORD     上级代理 Basic 认证密码
                                （与 --upstream-auth-user 配合使用）
RELAY_API_PORT                  控制 API / Web UI 端口覆盖
RELAY_MCP_PORT                  守护进程 MCP 端点端口覆盖
RELAY_PROXY_PORT                代理端口覆盖
RELAY_PROXY_IDLE_TIMEOUT        无流量多少秒后停代理（0 = 永不自动停）
RELAY_MCP_URL / RELAY_MCP_TOKEN MCP 桥直接使用的端点与令牌
RELAY_MCP_NO_AUTOSTART          设为 1 时 MCP 桥不得自行启动守护进程

完整的数据目录布局与参数优先级见配置。