HTTPeep CLI

概述

使用 httpeep-cli 通过终端操作 HTTPeep，适用于本地调试、自动化任务、CI 检查以及代理工作流。当 Codex 需要解析或总结命令输出时，请优先使用 --format json。

有关详细参数、示例及命令特定说明，请阅读 references/cli-reference.md。

操作流程

1. 在深入调试前，先验证 CLI 和代理状态：

httpeep-cli --version
httpeep-cli --format json proxy status
httpeep-cli proxy logs --lines 50

1. 根据任务需求启动或修复捕获：

httpeep-cli proxy start --port 8800
httpeep-cli proxy system status
httpeep-cli cert status

仅在用户需要系统级代理时使用 proxy system on。对于限定范围的交互式终端捕获，建议使用 httpeep-cli shell 或 hp shell；该命令会启动或复用代理，并进入一个子 Shell，其中已加载 HTTPeep 代理变量和运行时钩子。对于非交互式代理执行，应优先使用显式的应用代理环境变量，或采用 proxy start --capture-pid <pid> 方式，以避免代理阻塞在交互式 Shell 中。

1. 捕获并检查网络流量：

httpeep-cli --format json sessions list --keyword login
httpeep-cli --format json sessions watch --domain api.example.com

在执行破坏性清理操作前，请先使用过滤器筛选。尽可能先进行预演删除：

httpeep-cli sessions delete --keyword login --dry-run
httpeep-cli sessions clear --all --yes --dry-run

1. 在修改全局规则集前，先应用临时规则以实现可复现的测试：

httpeep-cli rules run \
  --map-remote "api.example.com=http://127.0.0.1:3000" \
  -- httpeep-cli request --method GET --url "https://api.example.com/users"

仅在需要持久化规则时才使用 rules upsert、rules import、rules replace 或 rules reset。在执行破坏性变更前，务必先导出现有规则：

httpeep-cli rules export --output rules-backup.json

1. 发送、重放或录制请求：

httpeep-cli --format json request --method GET --url "https://api.example.com/v2/users"
httpeep-cli replay --id <session_id> --retry-times 3 --retry-interval-ms 800
httpeep-cli record start
httpeep-cli record stop --output baseline.httpeep
httpeep-cli replay file baseline.httpeep

故障排查优先级

按以下顺序检查失败原因：

1. CLI 可用性：httpeep-cli --version
2. 代理引擎可达性：httpeep-cli --format json proxy status
3. 最近的代理日志：httpeep-cli proxy logs --lines 100
4. 应用路由配置：HTTP_PROXY、HTTPS_PROXY 或 httpeep-cli proxy system status
5. HTTPS 信任状态：httpeep-cli cert status，如需则执行 httpeep-cli cert install
6. 终端捕获 Shell 环境：httpeep-cli shell / hp shell 会创建 ~/.httpeep/automatic-setup/ 目录，并在子 Shell 中暴露 httpeep_intercept_off 变量
7. 输出解析问题：将相关命令重新运行并加上 --format json；注意 sessions watch --format json 输出为 NDJSON 格式

若 httpeep-cli 不在 PATH 中，请指导用户打开 HTTPeep 桌面设置，通过“设置 -> MCP -> 修复 CLI / PATH 安装”进行修复，或在可用时调用 MCP 修复工具。

调试证据记录

在复杂调试或多步骤捕获/重放任务中，应在最终答案或任务备注中记录简洁的追踪日志：

• 执行的命令及其关键参数
• 各主要步骤的时间戳或顺序编号
• 使用或生成的会话 ID
• 来自 sessions list、request、rules run 或 replay 的相关 JSON 字段
• 当涉及代理行为时，提供 httpeep-cli proxy logs --lines <n> 的摘要
• 应用的规则 ID 或临时规则快捷方式

避免记录来自请求头、Cookie、Authorization 值或请求体中的敏感信息。报告前请对敏感值进行脱敏处理。

安全默认设置

• 在修改持久规则前，优先使用 rules run、request 或 replay --id 等临时规则。
• 机器解析和 CI 日志中请始终使用 --format json。
• 除非用户明确希望进入交互式 Shell，否则不要从无头自动化路径运行 httpeep-cli shell；该命令会主动接管终端，直到子 Shell 退出。
• 破坏性会话清理操作前务必先进行预演（dry-run）。
• 执行 rules replace 或 rules reset 前，务必先导出规则。
• 仅当用户明确要求时，才运行 cert install、cert uninstall、proxy system on 或 proxy system off。
• 仅当用户明确要求时，才运行 rules replace、rules reset 或 sessions clear --all --yes。在可能的情况下，应先展示或执行备份/预演命令。
• 将 import curl、import har 和 import http 视为版本相关功能，因为部分 CLI 构建版本可能尚未实现这些命令。