CLI 参考

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

run

启动代理服务器。

relay-core-cli run [options]

监听与生命周期：
  -l, --listen <ADDR>           代理监听地址（默认 127.0.0.1:8080）
  -c, --control-port <PORT>     控制 API 端口（默认 8081）
      --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>  脚本可读取的环境变量名（逗号分隔）

TUI：
      --ui                        启用 TUI 交互界面
      --theme <NAME>             TUI 配色：relay、slate、high-contrast
                                  （覆盖 RELAY_CORE_TUI_THEME 与 config）

控制台输出（非 TUI）：
      --output <FORMAT>          table、json、jsonl（默认 table）
      --save-stream <PATH>       将所有流量以 JSONL 追加到该文件

REST / SSE HTTP API：
      --api-port <PORT>          启用 REST + SSE API
      --api-bind <ADDR>          绑定地址（默认 127.0.0.1）
      --api-token <TOKEN>        HTTP API Bearer 认证令牌
      --api-cors <ORIGINS>       CORS 允许源（逗号分隔）

上游代理：
      --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-cli 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-cli 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-cli 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

查看已捕获流量。不带任何参数时连接控制 WebSocket 打印实时流；只要带上了 --filter / --host / --path / --method / --status-min / --status-max / --has-error / --websocket / --limit 中的任一参数即进入 REST 搜索模式。

relay-core-cli flows [options]

连接：
      --control-url <URL>       实时流使用的控制 API（默认 http://127.0.0.1:8081）
      --api-url <URL>           搜索模式使用的 REST API（默认 http://127.0.0.1:8082）

搜索条件（需要代理启用 --api-port）：
      --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。

intercept

在不停机的情况下暂停或恢复拦截。调用旧版控制 API。

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

子命令：
  pause                         停止接受新的拦截决策
  resume                        恢复拦截

--control-url 默认 http://127.0.0.1:8081。

metrics

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

relay-core-cli 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 导出进行离线分析。

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

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

环境变量

RELAY_LOG                       日志过滤（如 info、debug、trace）
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_PORT                      relay-core-probe 代理端口（默认 8080）
RELAY_CA_CERT / RELAY_CA_KEY    relay-core-probe CA 路径
RELAY_PROBE_TRANSPORT           MCP 传输方式：stdio（默认）| sse
RELAY_PROBE_PORT                MCP SSE 监听端口（默认 3000）
RELAY_PROBE_BIND                MCP SSE 绑定地址（默认 127.0.0.1）

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