wecom-cli高级参数速查：--dry-run、--json、--set与自动分页--page-count用法清单-平芜编程栈

wecom-cli高级参数速查：--dry-run、--json、--set与自动分页--page-count用法清单

【免费下载链接】wecom-cli企业微信开放平台命令行工具 — 让人类和 AI Agent 都能在终端中操作企业微信项目地址: https://gitcode.com/gh_mirrors/we/wecom-cli

wecom-cli是企业微信开放平台命令行工具，让人类和 AI Agent 都能在终端中操作企业微信的消息、邮件、文档、待办、日程等业务。这篇速查清单聚焦 4 个最实用的高级参数：--dry-run（干跑预览）、--json（完整请求体）、--set（深层参数覆盖）与--page-count（自动分页），帮你少踩坑、写得快。

📋 30 秒速览：4 个高级参数一览表

参数	一句话作用	典型场景
`--dry-run`	只校验并打印将发送的请求，不实际调用	发重要操作前先预览
`--json '<JSON>'`	直接给定完整请求体 JSON 字符串	批量参数、复杂嵌套结构
`--set path=value`	深层路径覆盖，可重复，优先级最高	只改`--json`里的个别字段
`--page-count <n>`	游标式自动分页，最多拉取 n 页	列表类接口全量拉取

💡 三个"给请求体"的方式（命名参数 /--json/--set）可以自由组合，优先级从高到低是：--set> 命名参数 >--json。

🧪 --dry-run 干跑：先发预演，再真执行

--dry-run会在本地完成参数校验，并打印即将发送的完整请求，但不会发起任何 API 调用，stdout 会输出=== Dry Run ===预演信息。

适用场景：

发送消息、创建文档、修改日程等"写操作"前，确认请求体拼装无误
调试--json/--set组合出的最终 payload
验证--output-dir等路径参数是否合法（dry-run 与实际执行走同一道门禁校验，错误时机一致，详见 006-dry-run-output-dir-gate/desc.md）

# 预览：不会真正调用接口 wecom-cli message send --json '{"chat_id":"xxx","text":"周报"}' --dry-run

小技巧：也可以在--json里传{"dry_run": true}触发同样的干跑模式，效果与 flag 一致（见 018-json-extras-dry-run/desc.md）。

📦 --json：一行给完整请求体

--json直接接收完整请求体 JSON 字符串，适合参数多、嵌套深的接口，比一串命名参数更紧凑：

# 无参方法 wecom-cli message aibot sessions list # --json 给定请求体 wecom-cli doc search --json '{"keywords":["周报"],"limit":10}'

它的两个"容错设计"非常省心：

JSON 自动修复：尾部多逗号、未加引号的 key 等格式错误，会由内置修复器自动修正后正常解析（行为见 003-json-repair/desc.md），不用为引号问题来回排查
控制字段抽取：JSON 体里的dry_run、page_count等控制字段会被自动提取为对应 flag 生效，不会误发给服务端（如{"page_count": 2}直接触发分页，见 016-json-extras-pagination/desc.md）

🎯 --set：深层路径覆盖，优先级最高

--set path=value可以像"精准手术刀"一样覆盖请求体中任意深度的字段，可重复使用：

# 覆盖深层字段（可重复） wecom-cli doc search --json '{"keywords":["周报"],"limit":10}' \ --set limit=20 --set extra.flag=true

要点：

优先级最高：--set的赋值会覆盖--json与命名参数中的同路径字段
值支持 JSON 片段，非法片段同样会走自动修复
路径不存在时可以按需创建对象；若目标节点是标量无法展开，会报出清晰的--set a.b.c 参数标识 + 原因错误提示（实现见 assemble.rs）

典型用法：把一份标准--json模板固化下来，每次只--set改掉日期、ID 这类变化字段，脚本更稳定。

📄 --page-count：游标式自动分页

列表类接口默认只返回一页数据。加上--page-count <n>后，CLI 会依据响应的has_more+next_cursor自动翻页，最多拉取 n 页，输出为NDJSON（每行一页，方便jq逐行处理）：

# 最多拉 3 页，分页间隔 1 毫秒 wecom-cli message aibot sessions list --page-count 3 --page-delay 1

配套参数与行为：

--page-delay <ms>：分页请求间隔毫秒数，默认 100ms，批量拉取时可适当调大避免触发限流
提前终止：即使--page-count 5，服务端只有 2 页也会在has_more: false时停下，只输出 2 行（见 002-page-count-exceeds/desc.md）
全量拉取示例：mock 3 页数据的完整交互见 001-page-all/desc.md
想控制落盘目录，可配合--output把 NDJSON 多行结果直接写入文件