Use HTTPeep from the terminal with httpeep-cli for proxy lifecycle control, HTTP/HTTPS traffic capture, session inspection, rule injection, request replay, r...
--- name: httpeep-cli description: Use HTTPeep from the terminal with httpeep-cli for proxy lifecycle control, HTTP/HTTPS traffic capture, session inspection, rule injection, request replay, recording flows, certificate troubleshooting, CI scripting, and agent-driven network debugging. Use when a task mentions HTTPeep, httpeep-cli, proxy debugging, captured HTTP sessions, traffic rules, request replay, HTTPS interception certificates, or terminal-based traffic monitoring. --- # HTTPeep CLI ## Overview Use `httpeep-cli` to operate HTTPeep from the terminal for local debugging, automation, CI checks, and agent workflows. Prefer `--format json` for commands that Codex must parse or summarize. For detailed flags, examples, and command-specific notes, read `references/cli-reference.md`. ## Operating Workflow 1. Verify the CLI and proxy state before deeper debugging: ```bash httpeep-cli --version httpeep-cli --format json proxy status httpeep-cli proxy logs --lines 50 ``` 2. Start or repair capture depending on the task: ```bash httpeep-cli proxy start --port 8800 httpeep-cli proxy system status httpeep-cli cert status ``` Use `proxy system on` only when the user wants system-wide proxying. For scoped interactive terminal capture, suggest `httpeep-cli shell` or `hp shell`; it starts or reuses the proxy and enters a child shell with HTTPeep proxy variables and runtime hooks loaded. For non-interactive agent execution, prefer explicit app proxy environment variables or `proxy start --capture-pid <pid>` so the agent does not block inside an interactive shell. 3. Capture and inspect traffic: ```bash httpeep-cli --format json sessions list --keyword login httpeep-cli --format json sessions watch --domain api.example.com ``` Use filters before destructive cleanup. Always dry-run deletes when possible: ```bash httpeep-cli sessions delete --keyword login --dry-run httpeep-cli sessions clear --all --yes --dry-run ``` 4. Apply temporary rules for reproducible tests before changing the global ruleset: ```bash 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" ``` Use `rules upsert`, `rules import`, `rules replace`, or `rules reset` only when persistent rules are required. Export existing rules first before destructive changes: ```bash httpeep-cli rules export --output rules-backup.json ``` 5. Send, replay, or record requests: ```bash 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 ``` ## Troubleshooting Priority Check failures in this order: 1. CLI availability: `httpeep-cli --version` 2. Proxy engine reachability: `httpeep-cli --format json proxy status` 3. Recent proxy logs: `httpeep-cli proxy logs --lines 100` 4. App routing: `HTTP_PROXY`, `HTTPS_PROXY`, or `httpeep-cli proxy system status` 5. HTTPS trust: `httpeep-cli cert status`, then `httpeep-cli cert install` if needed 6. Terminal capture shell: `httpeep-cli shell` / `hp shell` creates `~/.httpeep/automatic-setup/` and exposes `httpeep_intercept_off` inside the child shell 7. Output parsing: rerun relevant commands with `--format json`; remember `sessions watch --format json` emits NDJSON If `httpeep-cli` is not on PATH, instruct the user to open HTTPeep desktop settings and use Settings -> MCP -> Repair CLI / PATH Installation, or call the MCP repair tool when available. ## Trace Evidence For complex debugging or multi-step capture/replay work, record a concise trace log in the final answer or task notes: - Commands executed, with important flags - Timestamp or sequence order for each major step - Session IDs used or produced - Relevant JSON fields from `sessions list`, `request`, `rules run`, or `replay` - Summary from `httpeep-cli proxy logs --lines <n>` when proxy behavior is involved - Rule IDs or temporary rule shortcuts applied Avoid logging secrets from headers, cookies, Authorization values, or request bodies. Redact sensitive values before reporting. ## Safety Defaults - Prefer temporary rules with `rules run`, `request`, or `replay --id` before persistent rule edits. - Use `--format json` for machine parsing and CI logs. - Do not run `httpeep-cli shell` from an unattended automation path unless the user explicitly wants an interactive shell; it intentionally takes over the terminal until the shell exits. - Dry-run destructive session cleanup first. - Export rules before `rules replace` or `rules reset`. - Run `cert install`, `cert uninstall`, `proxy system on`, and `proxy system off` only when the user explicitly asks for certificate trust or system-wide proxy changes. - Run `rules replace`, `rules reset`, or `sessions clear --all --yes` only when the user explicitly asks for persistent replacement, reset, or full cleanup. Show or run the backup/dry-run command first when possible. - Treat `import curl`, `import har`, and `import http` as version-dependent because some CLI builds may report that these commands are not yet implemented.
don't have the plugin yet? install it then click "run inline in claude" again.