-
Notifications
You must be signed in to change notification settings - Fork 0
CLI
ipclick 一共 20 条命令，按阶段分三组——这也是 ipclick --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、--token、--timeout、-J
|
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，
见安装。
ipclick -e toml > ipclick.toml 也能得到一份配置，但 init 多做四件：.env 用 600
权限创建、预填一个随机的 Web 管理端密码、目标文件已存在时不闷头覆盖、把 .env 追加进
.gitignore。
同一台机器起多个实例，用 -p 按端口命名：
ipclick init -p 8001 && ipclick init -p 8002 # 产出 ipclick-8001.toml / ipclick-8002.toml
ipclick run -p 8001 # 自动读 ipclick-8001.toml多实例还要注意 [TRACE].sqlite_path 与 [LOG].output 的 {port} 占位符，
见配置体系。
没有 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 只答"活没活"：grpc.health.v1 标准接口，免鉴权，健康退 0 否则 1，可以直接
塞进 Docker HEALTHCHECK 或 K8s 就绪探针。
HEALTHCHECK CMD ipclick health || exit 1status 多答"能干什么"：装了哪些适配器、浏览器本体就绪没、链路落盘开没开、集群里有
几个节点。发第一个请求之前该先问这一句——否则会指定一个本机根本没装的适配器，然后
对着 FAILED_PRECONDITION 猜半天。加 --probe-nodes 顺带把每个节点探一遍（会慢些）。
fetch 走的是和 SDK 完全相同的路径——SSRF 准入、按 host 限流、开了转发时的分发都在。
它不是"CLI 版的 curl"，而是"命令行形态的 IPClick 客户端"。
连哪个服务端
| 选项 | 说明 |
|---|---|
-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「调用」和「接入」两组的每一条命令都支持 -J/--json：输出单个 JSON 文档到
stdout，别的什么都不打。「部署」那四条不支持——它们是给人看的。
退出码分类，fetch 与 status 尤其依赖它：
| 码 | 含义 |
|---|---|
0 |
成功 |
1 |
失败（fetch 拿到响应但状态码 >= 400，除非加了 --ignore-status） |
3 |
连不上服务端 |
4 |
鉴权失败 |
5 |
参数或配置被拒 |
node probe 另有约定：任一节点不通时退 1。
命令行选项 > 环境变量 > 配置文件，完整优先级见配置体系。机密只从
.env 或环境走，不进 ipclick.toml：
IPCLICK_AUTH_TOKEN gRPC 鉴权令牌
IPCLICK_WEB_USER Web 管理端用户名
IPCLICK_WEB_PASSWORD Web 管理端密码
IPCLICK_CLUSTER_SECRET 集群共享密钥
IPCLICK_WEB_USER=ops IPCLICK_WEB_PASSWORD=... ipclick run -wtrace 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/连接失败）。
子节点部署材料只在 Web 管理端（登录后的集群页）生成，CLI 没有对应 命令。这是有意的：加一个"把配置写到远端"的接口，就等于拿下主控 = 能改所有机器上的配置 文件，包括 SSRF 拦截开关。所以是只生成、不推送，由人复制过去，攻击面一点没变。
完整流程：主控 Web 端生成材料 → 人工复制到子节点 → 子节点 ipclick run → 主控
ipclick node probe 验收。见集群。
卸组件不删浏览器本体。 component uninstall 只卸 Python 包——浏览器本体可能是
1 GB，从命令行递归删一个 GB 级目录是不可逆操作。用 component list 看它在哪、占多大，
自己决定。
两层，范围不一样：
「调用」那一组的命令，任何 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。