# CLI 详细命令 本文档集中说明 `bifrost` CLI 的所有顶层命令、主要子命令、环境变量和规则模板变量。若只想按使用场景快速上手，请先看 [CLI 快速开始](./cli-quick-start.md)。 ## 帮助与文档入口 ```bash bifrost --help bifrost --help bifrost --help ``` 顶层 `bifrost --help` 保持短输出：只展示常用示例、默认行为和关键文档链接，避免手写长参考与实际子命令参数漂移。详细参数以对应子命令 help 和本文档为准。 阅读原则： - 本文档解释“这个命令做什么、何时使用、如何组合使用”；每个参数的最终解析以 `bifrost --help` 为准。 - 会产生外部副作用的命令会明确标注，例如系统代理、shell rc 写入、远程 shell 执行、清空缓存、清除流量记录。 - `setting` 始终管理本机数据目录；`remote` 才会操作已连接的远端 Bifrost。不要把这两类命令混用。 - `--port` 在顶层和 `start` 中表示代理监听端口；在 `traffic list` 中 `--port` 表示 Admin API 端口，按流量入口端口过滤请用 `--listener-port` 或 `--proxy-port`。 关键文档： - [CLI 快速开始](./cli-quick-start.md)：按使用场景选择命令路径 - [安装与启动](./getting-started.md)：安装方式与首次启动 - [规则语法](./rule.md)：规则整体结构、过滤器、优先级 - [匹配器](./pattern.md)：domain / wildcard / regex / path wildcard 等匹配逻辑 - [操作符说明](./operation.md)：`host://`、`reqHeaders://`、`file://` 等 operation 的值格式 - [规则协议手册](./rules/README.md)：按协议分类的完整能力说明 ## 命令覆盖索引 | 命令 | 用途 | 本文档位置 | | --- | --- | --- | | `start` | 启动 HTTP/HTTPS/SOCKS5 代理，可配置 TLS 拦截、系统代理、规则、访问控制 | [`start` 命令](#start-命令) | | `stop` / `restart` / `status` | 停止、重启、查看代理状态 | [服务管理](#服务管理) | | `rule` | 管理本地规则：新增、更新、启停、排序、查看运行时 active 视图 | [规则管理](#规则管理) | | `group` | 管理远端/共享 Group 与 Group 规则 | [Group 管理](#group-管理) | | `port` | 绑定临时代理端口到显式规则集 | [临时端口规则绑定](#临时端口规则绑定) | | `ca` | 生成、安装、导出、查看 Bifrost CA | [CA 证书管理](#ca-证书管理) | | `whitelist` | 管理本机代理访问控制、待审批请求和临时放行 | [白名单管理](#白名单管理) | | `system-proxy` | 启用、禁用、查看操作系统代理 | [系统代理管理](#系统代理管理) | | `value` | 管理 `{VALUE_NAME}` 规则变量 | [Values 管理](#values-管理) | | `script` | 管理请求、响应、decode 脚本 | [Scripts 管理](#scripts-管理) | | `upgrade` / `version-check` | 检查新版本、升级二进制 | [升级与版本检查](#升级与版本检查upgrade--version-check) | | `config` | 查看和修改运行时配置、连接、缓存、性能状态 | [配置项管理](#配置项管理) | | `admin` | 管理 Admin 远程访问、密码、会话、审计日志 | [管理端远程访问与鉴权](#管理端远程访问与鉴权admin) | | `capture` | 等待下一条匹配条件的流量记录，适合浏览器/桌面应用联调和 Agent 采证 | [等待捕获](#等待捕获capture-wait) | | `traffic` / `search` | 查看、获取、搜索、导出、重放、诊断和清除流量记录 | [流量查看与搜索](#流量查看与搜索) | | `install-skill` | 安装 Bifrost Agent Skill 文档到 AI coding tools | [安装 Skill](#安装-skillinstall-skill) | | `ai voice` | 本地语音输入 runtime：来源探测、监听、词汇管理 | [本地语音输入](#本地语音输入ai-voice) | | `completions` | 生成 shell 补全脚本 | [Shell 补全](#shell-补全completions) | | `metrics` | 查看实时指标和历史指标 | [指标](#指标metrics) | | `sync` | 登录、退出、触发、配置远端同步服务 | [同步](#同步sync) | | `import` / `export` | 导入导出 `.bifrost` 规则、values、scripts 包 | [导入/导出](#导入导出import--export) | | `setting` | 管理本机 Shell Access policy/profile 与本机 remote-invoke grant | [本机 remote-invoke 设置](#本机-remote-invoke-设置setting) | | `remote` | 通过 relay 操作远端 Bifrost：连接、流量、文件、shell、keep-awake | [远程调用](#远程调用remote) | | `keep-awake` | 管理本机 macOS 防睡眠 | [macOS 防睡眠](#macos-防睡眠keep-awake) | | `im` | 管理 IM Gateway provider、target、route、schedule、消息历史 | [IM Gateway](#im-gatewayim) | ## 全局参数 ```txt bifrost [OPTIONS] [COMMAND] ``` | 参数 | 说明 | 默认值 | | --- | --- | --- | | `-p, --port ` | HTTP 代理端口 | `9900` | | `-H, --host ` | 监听地址 | `0.0.0.0` | | `--socks5-port ` | SOCKS5 端口 | 无 | | `-l, --log-level ` | 日志级别 | `info` | | `--log-output ` | 日志输出目标：`file` / `console` / `console,file`；默认写文件，显式 `console` 会额外输出到终端且仍保留文件日志 | `file` | | `--log-dir ` | 日志目录（默认：`/logs`） | 无 | | `--log-retention-days ` | 日志保留天数 | `7` | | `-h, --help` | 显示帮助 | - | | `-v, -V, --version` | 显示版本号 | - | ## 环境变量 这些变量会影响 CLI 或运行时行为。仅用于测试、构建或内部诊断的变量不应作为日常用户接口依赖。 | 变量 | 作用范围 | 说明 | | --- | --- | --- | | `BIFROST_DATA_DIR` | CLI 与服务运行时 | 覆盖数据目录。规则、values、scripts、证书、配置、日志和流量数据库都会写入该目录。日常使用优先复用默认数据目录和多端口隔离；自动化测试、并发实验或破坏性配置验证才建议设置临时目录。 | | `RUST_LOG` | 日志 | 覆盖 `-l/--log-level`，支持模块过滤，例如 `RUST_LOG=bifrost_proxy=debug,info bifrost start`。 | | `NO_COLOR` | CLI 输出 | 存在时禁用彩色输出，适合日志采集、CI、Agent 解析。 | | `FORCE_COLOR` | CLI 输出 | 存在时强制彩色输出，优先级高于终端自动检测。 | | `HTTP_PROXY` / `HTTPS_PROXY` / `ALL_PROXY` | CLI 发起的外部 HTTP 请求 | 影响升级检查、同步、远程 relay 等需要访问网络的 CLI 请求；也可能由 `--cli-proxy` 写入 shell rc 文件。 | | `NO_PROXY` | CLI 发起的外部 HTTP 请求 | 配合代理环境变量使用，声明不走代理的 host 或域名后缀。 | | `BIFROST_REMOTE_SSH_KEY` | `remote conn up --ssh-key` | 固定的 Remote Invoke SSH key 环境变量；当 `--ssh-key` 不带路径时读取该变量内容。 | | `BIFROST_FORCE_UPDATE_CHECK` | 版本检查 | 强制执行更新检查；主要用于调试或测试更新提示。 | | `BIFROST_INSTALL_SKILL_SOURCE` | `install-skill` | 选择 skill 安装源；正常用户通常无需设置。 | | `BIFROST_INSTALL_SKILL_DIR` | `install-skill` | 未显式传 `--dir` / `--cwd` 时覆盖全局 skill 安装目录；主要用于升级/E2E 测试隔离，避免写入真实 AI tool 目录。 | | `BIFROST_AGENT_HOME` | Agent 运行时 | Agent 配置和记忆目录的兼容覆盖项；默认优先使用 `$BIFROST_DATA_DIR/agent/`。 | | `BIFROST_AGENT_MODEL` / `BIFROST_AGENT_PROVIDER` | Agent 运行时 | 覆盖 Agent 默认模型和 provider。只影响 Agent 能力，不影响代理核心规则。 | | `BIFROST_AGENT_WORK_DIR` | Agent 运行时 | 覆盖 Agent 默认工作目录。 | 容易混淆的边界： - `--system-proxy` 修改操作系统代理配置；`--cli-proxy` 写入 shell rc 文件中的代理环境变量；`HTTP_PROXY` / `HTTPS_PROXY` 是当前进程继承到的环境变量。 - `BIFROST_DATA_DIR` 不只是配置目录，也决定当前 CLI 连接的 rules、values、scripts、certs、traffic DB 等状态来源。 - `RUST_LOG` 优先级高于命令行 `-l/--log-level`。如果你设置了 `RUST_LOG`，再改 `--log-level` 可能看起来“不生效”。 ## 规则变量速查 Bifrost 规则里有两类常见变量，含义不同： | 写法 | 来源 | 用途 | | --- | --- | --- | | `{NAME}` | 规则文件内嵌值，或少量确实需要全局共享的大型 Values | 在规则解析前展开。默认优先写内联 value 或规则文件内嵌值；特别大的 body/header/PAC 或跨很多规则复用时才放全局 Values | | `${name}` / `${name.property}` | 当前请求/响应上下文或环境变量 | 在请求处理时展开，适合引用 URL、headers、cookies、query、状态码 | | `$1` / `$2` | regex 或 wildcard 捕获组 | 在 pattern 命中后引用捕获结果 | | `$${name}` | 转义 | 输出字面量 `${name}`，不展开 | 常用模板变量： | 变量 | 含义 | | --- | --- | | `${url}` / `${host}` / `${hostname}` / `${port}` | 当前请求 URL、host、hostname、端口 | | `${path}` / `${pathname}` / `${search}` / `${query}` / `${query.name}` | 路径、查询字符串、指定 query 参数 | | `${method}` / `${statusCode}` / `${status}` | 请求方法、响应状态码 | | `${reqHeaders.name}` / `${reqH.name}` | 请求头；不带 `.name` 时返回全部请求头文本 | | `${resHeaders.name}` / `${resH.name}` | 响应头；仅在响应阶段有意义 | | `${reqCookies.name}` / `${resCookies.name}` | 请求或响应 cookie | | `${clientIp}` / `${clientPort}` / `${remoteAddress}` / `${remotePort}` | 客户端与远端连接信息 | | `${realUrl}` / `${realHost}` / `${realPort}` | Bifrost 解析到的真实请求信息 | | `${now}` / `${random}` / `${randomUUID}` / `${randomInt(n)}` / `${randomInt(a-b)}` | 时间和随机值 | | `${version}` / `${id}` / `${reqId}` | Bifrost 版本与请求 ID | | `${env.NAME}` | 读取当前 Bifrost 进程环境变量 `NAME` | 高级模板写法： ```txt api.example.com reqHeaders://X-Path=${path} api.example.com reqHeaders://X-Encoded=${{url}} api.example.com reqHeaders://X-Host=${hostname.replace(example,test)} api.example.com file://({"literal":"$${host}"}) ``` 更多变量、URL 编码、replace 语法和数据对象格式见 [操作符说明](./operation.md)。 ## `start` 命令 常见示例： ```bash bifrost start bifrost start --daemon bifrost restart bifrost -p 9000 start bifrost -p 9000 --socks5-port 1080 start bifrost start --no-intercept bifrost start --intercept-exclude "*.example.com,internal.corp.com" bifrost start --intercept-include "*.api.local" bifrost start --app-intercept-include "*Chrome,*curl" bifrost start --app-intercept-exclude "*PinnedApp" bifrost start --rules "example.com host://127.0.0.1:3000" bifrost start --rules-file ./my-rules.txt bifrost start --access-mode whitelist --whitelist "192.168.1.100,10.0.0.0/8" bifrost start --allow-lan bifrost start --proxy-user admin:password123 bifrost start --system-proxy bifrost start --disable-badge-injection bifrost start --enable-badge-injection ``` `bifrost start` 默认会启用系统代理，最快让浏览器和桌面应用流量进入 Bifrost。TLS 抓包不是默认建议，应按需通过规则级 `tlsIntercept://`、`--intercept-include` 或 `--app-intercept-include` 收窄到目标域名/应用；遇到 SSL pinning 应用时，用 `tlsPassthrough://`、`--intercept-exclude` 或 `--app-intercept-exclude` 排除。需要 TLS 抓包时，服务启动流程会自动生成并安装 Bifrost CA；`ca generate` / `ca install` 主要用于手动修复或诊断证书状态。默认访问控制模式为 `interactive`：本机 loopback 直接允许，非本机地址需要管理端审批、白名单或显式 `--allow-lan` / `--access-mode` 放行。`--no-system-proxy`、`--unsafe-ssl` 和 `--skip-cert-check` 是测试/诊断选项，不应作为普通启动路径。 当检测到已有 Bifrost 进程在运行时，`bifrost start` 会在终端提示是否重启：输入 `y/yes` 将停止旧进程并重新启动；输入 `n/no` 将取消本次启动。 如果需要在脚本/CI 中跳过交互，可以使用 `-y/--yes` 自动确认重启。 参数摘要： | 参数 | 说明 | | --- | --- | | `-d, --daemon` | 守护进程模式 | | `--skip-cert-check` | 跳过 CA 证书安装检查，仅用于你明确知道证书状态且需要继续测试的场景；普通启动会自动处理 CA | | `--access-mode ` | `local_only` / `whitelist` / `interactive` / `allow_all` | | `--whitelist ` | 客户端 IP 白名单，支持 CIDR | | `--allow-lan` | 允许局域网访问 | | `--proxy-user ` | 代理认证账号（可重复指定） | | `--intercept` | 启用全局 TLS 抓包；不要作为默认启动参数，优先使用域名/应用白名单或规则级 `tlsIntercept://` | | `--no-intercept` | 禁用 TLS 拦截 | | `--intercept-exclude ` | TLS 拦截排除域名 | | `--intercept-include ` | TLS 拦截白名单（最高优先级，即使全局关闭也生效） | | `--app-intercept-exclude ` | TLS 拦截排除应用（进程名通配） | | `--app-intercept-include ` | TLS 拦截应用白名单（最高优先级） | | `--unsafe-ssl` | 跳过上游证书校验，仅用于证书异常诊断或隔离测试；普通 HTTPS 调试应让启动流程自动处理 CA 并保持证书校验 | | `--enable-badge-injection` | 强制启用 HTML 页面注入 Bifrost 小圆点（会持久化到配置） | | `--disable-badge-injection` | 禁用 HTML 页面注入 Bifrost 小圆点（会持久化到配置） | | `--no-disconnect-on-config-change` | TLS 配置变更时不自动断开受影响连接 | | `--rules ` | 直接传入规则，可多次指定 | | `--rules-file ` | 从文件加载规则 | | `--system-proxy` | 启动后自动设置系统代理 | | `--proxy-bypass ` | 系统代理绕过列表 | | `--cli-proxy` | 运行期间写入命令行代理环境变量 | | `--cli-proxy-no-proxy ` | 命令行代理 no-proxy 列表 | | `-y, --yes` | 自动确认交互提示（如已运行进程的重启确认） | ## 常用命令 ### 服务管理 ```bash bifrost status bifrost status --tui bifrost stop bifrost restart bifrost restart --port 9900 --host 127.0.0.1 --log-level debug bifrost restart --force ``` `restart` 会停止当前代理并启动一个新的后台 daemon，常用于 `bifrost upgrade` 后让运行中的服务切到新二进制。该命令会把新进程与当前终端管道解耦，因此也适合通过 `bifrost remote exec` 远程触发。 ### 临时端口规则绑定 ```bash bifrost port bind --port 18888 --rule local-dev bifrost port bind --port 18889 --rule local-dev --group-rule 7152084678483132446/abc bifrost port bind --port 0 --rule-file ./temp-rule.bifrost bifrost port bind --port 18890 --rule-text "debug.test status://218 resBody://(debug)" bifrost port list bifrost port show 18888 bifrost port active 18888 bifrost port update 18888 --rule another-local-rule bifrost port update 18888 --rule-file ./updated-temp-rule.bifrost bifrost port destroy 18888 ``` `port` 命令需要主代理正在运行。临时端口与主端口共享同一个 `BIFROST_DATA_DIR` 中的规则、values、scripts、证书、流量记录等数据；端口绑定只保存“这个端口选择哪些规则集”。临时端口流量不受默认规则 enabled/disabled 状态影响：只有 `port bind` / `port update` 显式绑定的本地规则或 Group 规则会进入该临时端口的 resolver。 `--rule` 引用本地规则名；`--group-rule` 使用 `/` 格式；`--rule-file` 直接绑定规则文件；`--rule-text` 直接绑定规则原文。销毁临时端口只关闭该端口监听，不删除共享规则数据，也不影响主端口。 临时端口绑定状态只在当前运行进程内存里生效，不写入持久配置。Bifrost 重启后临时端口会被重置，不会自动重新监听，也不会恢复之前的规则绑定；需要时请重新执行 `bifrost port bind ...`。 Traffic 记录会带监听端口信息，即使请求没有命中任何规则也会记录来源端口：`traffic list` 的表格包含 `PORT` 列，JSON compact 字段为 `lp`，`traffic get` 详情字段为 `listener_port`。这用于区分同一数据目录内主端口和临时端口产生的流量。 多端口推荐工作流： 1. 先确认主代理已运行；默认用 `bifrost start`。如需 HTTPS 明文调试，优先在任务规则里使用 `tlsIntercept://`，或用 `--intercept-include` / `--app-intercept-include` 只放行目标域名/应用。 2. 保持主端口继续承载默认启用规则。 3. 为临时调试场景按需再开多个端口： - `bifrost port bind --port 18888 --rule local-dev` - `bifrost port bind --port 18889 --group-rule 7152084678483132446/abc` - `bifrost port bind --port 0 --rule-file ./temp-debug.bifrost` - `bifrost port bind --port 18890 --rule-text "debug.test status://218 resBody://(debug)"` 4. 用 `bifrost port list` 查看当前所有临时端口；用 `bifrost port show ` 看绑定元信息；用 `bifrost port active ` 看这个端口当前真正生效的规则视图。 5. 当一个临时端口需要切换到另一组规则时，使用 `bifrost port update ...` 传入新的完整规则引用集合。 6. 调试结束后执行 `bifrost port destroy ` 回收对应监听端口。 同一个 Bifrost 服务可以同时服务多个应用或开发任务。推荐做法是共享一个常驻主服务，让系统代理、CA、Web UI 和 traffic 存储保持统一；每个应用、任务或 Agent 分配一个独立入口端口，并只在该端口绑定对应规则： ```bash bifrost port bind --port 18881 --rule-text "app-a.example.com tlsIntercept:// host://127.0.0.1:3001" bifrost port bind --port 18882 --rule-text "app-b.example.com tlsIntercept:// host://127.0.0.1:3002" bifrost traffic list --listener-port 18881 --limit 50 bifrost traffic list --listener-port 18882 --limit 50 ``` 给 Agent 排查或生成 skill 时，应在指令中明确入口端口，例如“只分析 `listener_port=18882` 的流量”。这能避免多个应用共享同一个 traffic 数据库时，把其他任务的请求混入协议理解。 规则来源选择建议： | 方式 | 适用场景 | 示例 | | --- | --- | --- | | `--rule` | 复用已有本地规则 | `bifrost port bind --port 18888 --rule local-dev` | | `--group-rule` | 复用已有 Group 规则 | `bifrost port bind --port 18889 --group-rule 7152084678483132446/abc` | | `--rule-file` | 一次性加载本地规则文件，不写入共享规则目录 | `bifrost port bind --port 0 --rule-file ./temp-debug.bifrost` | | `--rule-text` | 临时写一条短规则快速排障 | `bifrost port bind --port 18890 --rule-text "debug.test status://218 resBody://(debug)"` | 帮助文档检查点： - `bifrost --help` 应能看到 `port` 顶层命令。 - `bifrost port --help` 应解释主端口与临时端口的职责差异。 - `bifrost port bind --help` / `bifrost port update --help` 应解释四类规则来源和 `--port 0` 自动分配行为。 ### 流量查看与搜索 ```bash bifrost traffic list bifrost traffic list --method GET --status-min 400 --limit 100 bifrost traffic list --listener-port 50831 --format json bifrost traffic list --proxy-port 50831 --format json bifrost traffic list --client-app Chrome --limit 50 bifrost capture wait --host api.example.com --method POST --path /v1/login --timeout 30s bifrost capture wait --host api.example.com --timeout 10s --format json bifrost traffic get --request-body --response-body bifrost traffic get --ids 1,2,3 --request-body --response-body --format ndjson bifrost traffic get --ids 1,2,3 --request-body --response-body --max-body 32768 bifrost traffic auth-status bifrost traffic auth-status --format json bifrost traffic export --as curl bifrost traffic export --as fetch bifrost traffic export --as har -o ./request.har bifrost traffic replay bifrost traffic replay --patch '/json/user/name="debug"' bifrost traffic replay --patch-json '[{"op":"replace","path":"/json/user/name","value":"debug"}]' bifrost traffic search "keyword" bifrost traffic search "keyword" --listener-port 50831 bifrost traffic search "keyword" --proxy-port 50831 bifrost search "keyword" bifrost search "keyword" --method POST --host api.openai.com --path /v1/responses bifrost search "keyword" --req-header bifrost search "keyword" --res-body bifrost search "" --host api.example.com --req-json '$.user.id=42' --include request-body,response-body bifrost search "" --host api.example.com --res-json '$.error.code=invalid_request' --latest 15m bifrost search "token" --req-header-eq authorization="Bearer ..." --since 2026-01-01T00:00:00Z --until 2026-01-01T01:00:00Z ``` `bifrost search` 与 `bifrost traffic search` 等价，支持关键词搜索、基础过滤器、结构化 JSONPath / Header 精确匹配、时间范围、返回内容 include 与搜索范围控制。`traffic get` 默认查询单条详情；需要一次交给 Agent 或脚本分析多条记录时，用 `--ids` 批量读取，批量输出推荐 `--format ndjson`，避免把多条大响应合成一个巨大 JSON。 本期不做 Authorization、Cookie、JWT token 等敏感信息脱敏。`traffic get`、`traffic export`、`search --include` 输出均按捕获原文返回；完整脱敏方案会另开需求处理，当前不要把这些输出粘贴到低信任渠道或可复用文档。 基础过滤器： | 参数 | 说明 | | --- | --- | | `--method ` | 按 HTTP 方法过滤，如 `GET`、`POST` | | `--host ` | 按 Host 包含匹配过滤 | | `--url ` | 按完整 URL 包含匹配过滤，仅 `traffic list` 支持 | | `--path ` | 按 Path 包含匹配过滤 | | `--status ` | `traffic list` 中为精确状态码，如 `404`；`search` 中为状态段，如 `2xx`、`4xx`、`5xx`、`error` | | `--status-min ` / `--status-max ` | 按状态码上下界过滤，仅 `traffic list` / `remote traffic list` 支持 | | `--protocol ` | `traffic list` 使用小写 `http` / `https` / `ws` / `wss` / `h3`；`search` 使用大写 `HTTP` / `HTTPS` / `WS` / `WSS` | | `--domain ` | 按域名模式过滤 | | `--content-type ` | 按内容类型过滤，如 `json`、`html`、`form` | | `--client-ip ` | 按客户端 IP 过滤，仅 `traffic list` 支持 | | `--client-app ` | 按客户端应用或进程名过滤，适合只分析某个浏览器、桌面应用或 CLI 工具产生的流量 | | `--listener-port ` / `--proxy-port ` | 按流量入口代理端口过滤；`traffic list` 中的 `--port` 仍表示 Admin API 端口 | | `--req-json ` / `--res-json ` | 按请求体或响应体 JSONPath 值过滤；适合不用关键词、只按结构字段定位请求 | | `--req-header-eq ` / `--res-header-eq ` | 按请求头或响应头精确值过滤 | | `--since