CLI

命令行

ipclick 有 11 个顶层命令（其中 trace / node / component / config / skill 各带子命令，算到底一共 19 条）。--help 只按字母平铺列出，下面这个三段分法是本文 为了讲清用途加的：

• 部署：给人用的。装好、起起来、确认活着。init / run / health / config-info
• 调用：给程序（尤其是 AI）用的。全部支持 --json，退出码分类。 status / fetch / trace / node / component / config
• 接入：把技能包交给 AI 代理。skill

不带子命令跑 ipclick 会打印帮助，不会静默退出。

全部命令

阶段	命令	作用	关键选项	命令示例
全局	--version	打印版本	—	ipclick --version
全局	-e	输出配置模板到 stdout	-e toml（默认）、-e env	ipclick -e env > .env
部署	init	生成 ipclick.toml + .env	-f 强制覆盖、-d 目录、-p 按端口命名	ipclick init -p 8001
部署	run	启动 gRPC 服务端	-c 配置、-p 端口、--host 绑定地址、-v DEBUG 日志	ipclick run -c ipclick.toml -p 50051
部署	run -w	顺带起 Web 管理端（登录信息打到控制台）	--web-port、--web-host、--web-lan	ipclick run -w --web-lan --web-port 8080
部署	health	grpc.health.v1 探活。健康退 0，否则 1	--host、-p、-c、--service、--timeout（5s）	ipclick health -p 50051
部署	config-info	给人看的一屏配置摘要	-c	ipclick config-info
调用	status	服务端在不在 + 这台机器能干什么	--probe-nodes、-c、--host、-p、--timeout、-J（--token 存在但不生效：健康检查免鉴权，节点探测用 [CLUSTER].secret 派生令牌）	ipclick status --probe-nodes -J
调用	fetch URL	通过服务端发一次请求	见下节	ipclick fetch https://example.com -J
调用	trace list	列最近的请求记录	-n 条数、--offset、--status、--adapter、-k URL 关键字、--since 小时、-c、-p	ipclick trace list -n 50 --status error --since 24
调用	trace stats	成功率、耗时、按天趋势、站点排行	--days（7）、--top（10）、-c、-p	ipclick trace stats --days 30 --top 20
调用	node list	列 [CLUSTER].nodes 里声明的节点	-c、-J	ipclick node list -J
调用	node probe [NODE_ID]	探节点：连得上吗、鉴权配对吗	--address host:port、--timeout（5s）、-c、-J	ipclick node probe --address 10.0.0.2:50051
调用	component list	列五个可选组件的安装状态	-c、-J	ipclick component list
调用	component install EXTRA	装组件的 Python 包	--dry-run、-J	ipclick component install niquests
调用	component uninstall EXTRA	卸组件的 Python 包	--dry-run、-J	ipclick component uninstall playwright
调用	component browser EXTRA	下载浏览器本体	--kind chromium|firefox|webkit、--dry-run、-J	ipclick component browser patchright --kind chromium
调用	config show	输出生效配置（机密脱敏）	-s 只看某一节、-c、-J	ipclick config show -s SERVER -J
调用	config get PATH	取一项配置的值	-c、-J	ipclick config get DOWNLOADER.retry.max_attempts
接入	skill show	把技能包正文打到 stdout	-J	ipclick skill show > SKILL.md
接入	skill install	装进项目让本地 AI 代理发现	-d 目录、-f 覆盖、-J	ipclick skill install -f
接入	skill path	包内那份技能文件在哪	-J	ipclick skill path

五个 EXTRA：niquests / camoufox / patchright / playwright / drissionpage， 见安装。

部署那一组

init 比 -e 重定向多做的事

ipclick -e toml > ipclick.toml 也能得到一份配置，但 init 多做四件：.env 用 600 权限创建、预填一个随机的 Web 管理端密码、目标文件已存在时不闷头覆盖、把 .env 追加进 .gitignore。

同一台机器起多个实例，用 -p 按端口命名：

ipclick init -p 8001                # 产出 ipclick-8001.toml，外加共用的 .env
ipclick -e toml > ipclick-8002.toml # 第二个实例只要模板，改掉里面的 port
ipclick run -p 8001                 # 自动读 ipclick-8001.toml

第二个实例不能再 init 一次。 init 的存在性检查把 .env 也算在内， 第一次已经生成过它，所以第二条 init 会直接中止（加 -f 又会重写 .env， 把随机出来的 Web 密码换掉）。要两份完整的机密就用 -d 换目录。 -p 只改 [SERVER].port，.env 是共用的。

多实例还要注意 [TRACE].sqlite_path 与 [LOG].output 的 {port} 占位符， 见配置体系。

Web 管理端只能随 run 起

没有 ipclick web 这条命令——Web 端挂在服务端进程里，-w 是它唯一的开关。

ipclick run -w                          # 只监听本机
ipclick run -w --web-lan                # 监听所有网卡，局域网可访问
ipclick run -w --web-port 8080          # 同目录多实例时必须岔开，否则第二个起不来

--web-lan 是 --web-host 0.0.0.0 的简写。两个都给且不一致会直接报错，不会悄悄让 一个赢——让人对着一个自己没写过的监听地址排查半天是更坏的结果。开放到本机以外时会在 启动前打一条警告：那是明文 HTTP，密码在网络上裸奔，见安全。

health 和 status 的分工

health 只答"活没活"：grpc.health.v1 标准接口，免鉴权，健康退 0 否则 1，可以直接 塞进 Docker HEALTHCHECK 或 K8s 就绪探针。

HEALTHCHECK CMD ipclick health || exit 1

status 多答"能干什么"：装了哪些适配器、浏览器本体就绪没、链路落盘开没开、集群里有 几个节点。发第一个请求之前该先问这一句——否则会指定一个本机根本没装的适配器，然后 对着 FAILED_PRECONDITION 猜半天。加 --probe-nodes 顺带把每个节点探一遍（会慢些）。

fetch 的选项分四组

fetch 不是"CLI 版的 curl"，而是"命令行形态的 IPClick 客户端"：服务端侧的 SSRF 准入、按 host 限流、以及 forward = "on" 的服务端转发都照常生效。

有一处例外值得知道：它固定用单机客户端 Downloader，不读 [GENERAL].mode， 所以集群的客户端分发模式（mode = "cluster" + forward = "off"）它用不上—— 要那个得走 SDK 的 create_client()。

连哪个服务端

选项	说明
-c, --config PATH	配置文件路径，默认找当前目录的 ipclick.toml
--host TEXT	服务端地址，默认取配置（[::] / 0.0.0.0 会当成 127.0.0.1）
-p, --port INTEGER	服务端端口，默认取配置
--token TEXT	gRPC 鉴权令牌，覆盖 IPCLICK_AUTH_TOKEN 与配置文件

请求长什么样

选项	说明
-X, --method TEXT	HTTP 方法，默认 GET
-H, --header TEXT	请求头 'Name: value'，可重复
--cookie TEXT	Cookie 'k=v'，可重复
--param TEXT	查询参数 'k=v'，可重复
-d, --data TEXT	请求体。@路径 从文件读，@- 从 stdin 读
--json-body TEXT	JSON 请求体（一段 JSON 文本；@路径 从文件读）

怎么发

选项	说明
-a, --adapter TEXT	适配器：curl_cffi / niquests / browser / camoufox …
--proxy TEXT	代理 URL；填 config 表示用配置文件里的 [PROXY]
--impersonate TEXT	curl_cffi 的浏览器指纹，如 chrome124
--timeout FLOAT	单次请求超时，默认 60 秒
--retries INTEGER	适配器内部重试次数，默认 3
--no-verify	不校验目标站点的 TLS 证书
--no-redirects	不跟随重定向

结果怎么给

选项	说明
-o, --output PATH	把响应体完整写进文件（不截断）
--max-body INTEGER	--json 输出里响应体的字符上限，默认 65536；0 = 不限制
--ignore-status	只要拿到了响应就算成功（4xx/5xx 也退出 0）
-J, --json	输出单个 JSON 文档到 stdout

几个组合：

# POST 一段 JSON，用真实浏览器渲染，结果给程序解析
ipclick fetch https://example.com/api -X POST --json-body @body.json -a camoufox -J

# 从 stdin 读请求体，走配置里的代理
cat payload.txt | ipclick fetch https://example.com -X POST -d @- --proxy config

# 下大文件：响应体落盘，不进 JSON
ipclick fetch https://example.com/big.zip -o big.zip

--json 契约与退出码

「调用」和「接入」两组的每一条命令都支持 -J/--json：输出单个 JSON 文档到 stdout，别的什么都不打。「部署」那四条不支持——它们是给人看的。

退出码分类，fetch 与 status 尤其依赖它：

码	含义
0	成功
1	失败（fetch 拿到响应但状态码 >= 400，除非加了 --ignore-status）
2	用法错误：适配器名或 HTTP 方法拼错、-H / --cookie / --param 格式不对、--json-body 不是合法 JSON。Click 自己的 UsageError 也是这个码
3	连不上服务端
4	鉴权失败
5	参数或配置被拒

2 和 5 的分界：2 是命令行本身写错了（改命令），5 是参数合法但被服务端或 本地配置拒掉（改配置或调用参数）。

node probe 另有约定：任一节点不通时退 1。

环境变量

命令行选项 > 环境变量 > 配置文件，完整优先级见配置体系。机密只从 .env 或环境走，不进 ipclick.toml：

IPCLICK_AUTH_TOKEN            gRPC 鉴权令牌
IPCLICK_WEB_USER              Web 管理端用户名
IPCLICK_WEB_PASSWORD          Web 管理端密码
IPCLICK_PROXY_AUTH_KEY        代理账号
IPCLICK_PROXY_AUTH_PASSWORD   代理密码
IPCLICK_CLUSTER_SECRET        集群共享密钥

正好这六项，ipclick -e env 生成的模板与 config-info 审计的来源都是这一份清单。

非机密的部署参数（IPCLICK_HOST / PORT / MAX_WORKERS / MODE / LOG_LEVEL / CLUSTER_SELF_ID）也能走环境变量，但刻意不预置在 .env 模板里——那份文件只放机密， 混进普通配置项就会让人忘记它不该进版本库。

IPCLICK_WEB_USER=ops IPCLICK_WEB_PASSWORD=... ipclick run -w

trace 只能查落盘的那部分

trace list / trace stats 直接读 [TRACE].sqlite_path 那个库，不经过服务端。 内存环形缓冲活在服务端进程里，别的进程够不到——要看那一份请开 [TRACE].sqlite_enabled，或用 Web 端的「请求流」。见链路记录。

因为不连服务端，这两条的 -p 含义和别处不同：只用于解析路径里的 {port} 占位符， 不是"连哪个端口"。同目录多实例时不给 -p 会读错库。

ipclick trace list -p 8001 -n 50 --status error

--status 可选 2xx / 3xx / 4xx / 5xx / failure / error，其中 error = 所有失败（4xx/5xx/连接失败）。

CLI 里没有的两件事

子节点部署材料只在 Web 管理端（登录后的集群页）生成，CLI 没有对应 命令。这是有意的：加一个"把配置写到远端"的接口，就等于拿下主控 = 能改所有机器上的配置 文件，包括 SSRF 拦截开关。所以是只生成、不推送，由人复制过去，攻击面一点没变。

完整流程：主控 Web 端生成材料 → 人工复制到子节点 → 子节点 ipclick run → 主控 ipclick node probe 验收。见集群。

卸组件不删浏览器本体。 component uninstall 只卸 Python 包——浏览器本体可能是 1 GB，从命令行递归删一个 GB 级目录是不可逆操作。用 component list 看它在哪、占多大， 自己决定。

给 AI 用

两层，范围不一样：

「调用」那一组的命令，任何 AI、任何程序都能用。 没有任何 Claude 专属的东西，就是 普通 CLI 加两条契约：--json 输出单个 JSON 文档、退出码分类。GPT、Gemini、开源模型、 LangChain 的 tool、CI 里的 bash，都一样。

skill 那三条目前只有 Claude Code 会自动发现。 skill install 默认写 ./.claude/skills/ipclick/SKILL.md，那是 Claude Code 的项目级技能位置，文件是 Claude Agent Skill 格式（YAML frontmatter 说明"什么时候该用我"，正文是操作手册）。

但内容是纯 Markdown，谁都能读。给别的 AI 用就手动喂：

ipclick skill show > /path/to/your-agent/ipclick-manual.md   # 塞进系统提示或知识库
ipclick skill install -d .cursor/rules                        # 或装到别的目录

能不能被发现取决于那个工具自己的约定，IPClick 只负责把文件写过去。

技能包随 wheel 分发而不是写在 README 里，是为了保证模型拿到的用法说明和这台机器上装 的这个版本一致——版本一升级，重装一次技能包，用法说明跟着变。Web 管理端也提供同一份： 登录后打开 /skill，或直接下载 /skill.md。

下一步

• 用 Python 而不是命令行 → SDK 用法
• 现成命令片段 → 示例集
• 退出码 3 / 4 是什么意思 → 故障排查