wecomteam--wecom-cli/docs/cli-reference.md

CLI 命令参考

本文档描述 wecom-cli 的命令模型、参数约定、运行时路径、环境变量与错误格式。

命令模型

wecom-cli 的命令分为四类：

形态	说明
wecom-cli <service> [resource...] <method> [flags]	调用远程服务方法。service 由服务端 discovery 动态下发，方法可能带嵌套资源路径（如 message aibot sessions list）
wecom-cli <service> +<helper> [flags]	本地 helper（+ 前缀），由产品层注册
wecom-cli auth <init|show>	授权管理（内建扩展命令）
wecom-cli schema ... / wecom-cli cache ...	内建命令（隐藏在 --help 之外，见下文）

说明：

• 服务目录与工具 schema 均在线获取，因此查看帮助与调用工具需要凭证与网络。
• 可用的 service 列表以 wecom-cli --help 实际输出为准。常见品类：message（消息）、mail（邮件）、doc（在线文档/文档管理）、sheet（在线表格）、smartsheet（智能表格）、smartpage（智能文档）、calendar（日程）、meeting（会议）、todo（待办）、disk（微盘）、contact（通讯录）、media（媒体文件）、identity（身份）。

配置凭证 auth

交互式配置企业微信机器人凭证，加密存储到本地（见「运行时路径」）。仅需执行一次：

# 配置凭证（交互式选择接入方式；非交互环境自动使用扫码接入）
wecom-cli auth init

# 查看授权状态
wecom-cli auth show

支持两种接入方式：

• 扫码接入（推荐）：终端展示二维码，使用企业微信扫码创建绑定；扫码等待超时为 5 分钟
• 手动接入：输入 Bot ID 和 Secret，获取方式参考

auth init 参数

参数	说明
--noninteractive	跳过交互选择，直接使用扫码接入（CI/脚本/管道等非交互环境适用）
--no-browser	扫码时不自动打开浏览器
--output-qrcode <PATH>	将二维码输出为 PNG 文件（仅支持当前目录下的路径，如 qr.png）
--manual	跳过交互选择，手动输入 Bot ID 和 Secret（需要终端）

auth show 参数

默认输出人类可读的 Status 与 Bot ID。

参数	说明
--status	仅输出 authorized / unauthorized 单行，便于脚本判断

查看帮助 --help

支持获取各级命令的使用方式：

# 列出所有支持的命令和品类
wecom-cli --help

# 列出指定品类下的所有工具
wecom-cli <service> --help

# 列出指定工具所需的输入
wecom-cli <service> [resource...] <method> --help

此外，每个服务与方法都支持文档 flag：

• wecom-cli <service> --schema / --doc：输出服务 schema / 文档
• wecom-cli <service> <method> --schema / --doc：输出方法 schema / 文档（含 TS 类型声明）

--version 输出格式：wecom-cli <version> (<distribution> <RFC 3339 构建时间> <git_commit_id>)。

调用工具

通用格式：

wecom-cli <service> [resource...] <method> [--param value ...] [--json '<JSON>'] [flags]

请求体有三种给出方式，可组合：

方式	说明
命名参数	由方法 schema 生成的 clap 参数（如 --id root），类型与必填性以 --help 为准
--json '<JSON>'	直接给定完整请求体 JSON 字符串
--set path=value	深层路径覆盖，可重复（如 --set extra.flag=true）；非法 JSON 片段会自动修复

示例：

# 无参方法（含嵌套资源路径）
wecom-cli message aibot sessions list

# --json 给定请求体
wecom-cli doc search --json '{"keywords":["周报"],"limit":10}'

执行相关 flag（所有方法通用）：

Flag	说明
--dry-run	仅在本地校验并打印将发送的请求，不实际调用
--page-count <n>	启用游标式自动分页，最多拉取 n 页；输出为 NDJSON（每行一页）
--page-delay <ms>	分页请求间隔毫秒数，默认 100
--output / -o <file>	将响应体写入文件
--output-dir <dir>	将响应与附件写入目录（分页时生成 <method>.ndjson）

输出形态：

• 默认：compact JSON 输出到 stdout
• 写文件/下载：stdout 输出 DownloadResult JSON（含 content_type、file_path、size），文件以 0600 权限落盘
• 分页：NDJSON 多行输出

内建命令

以下命令隐藏在 --help 之外，面向调试与集成场景：

wecom-cli schema list                        # 列出所有服务及方法 schema
wecom-cli schema get <service.resource.method>  # 获取指定方法 schema（点分隔路径）
wecom-cli cache status                       # 查看 discovery 缓存状态
wecom-cli cache clear                        # 清除所有 discovery 缓存

运行时路径

项目	默认位置	备注
配置目录	~/.config/wecom	可由 WECOM_CLI_CONFIG_DIR 覆盖
凭据文件	<config_dir>/credentials.enc	auth init 时创建；AES-256-GCM 加密（0600），bot 信息与 token 共存于同一文件
加密密钥	系统 keyring 或 <config_dir>/.encryption_key	无系统 keyring 时的文件回退（0600）
discovery 缓存	<config_dir>/cache	服务目录与 schema 缓存，TTL 60 秒
临时目录	<system_tmp>/wecom	媒体下载、请求暂存等；可由 WECOM_CLI_TMP_DIR 或 config.json 的 tmp_dir 覆盖

环境变量

变量	作用
WECOM_CLI_CONFIG_DIR	覆盖默认配置目录
WECOM_CLI_TMP_DIR	覆盖临时目录根目录
WECOM_CLI_ADDITIONAL_HEADERS	额外请求头，值为 JSON object（Record<string, string>）；同时支持 WECOM_CLI_ADDITIONAL_HEADERS_* 后缀形式的多个变量，取值同为 JSON object
WECOM_CLI_LOG_LEVEL	打开 stderr 文本日志并设置过滤级别（如 debug、wecom=trace；非法值回退 warn）
WECOM_CLI_LOG_DIR	打开 JSON Lines 日志输出，按天写入 <dir>/ww.log.<日期>（UTC+8）

配置文件 config.json

存放于 <config_dir>/config.json，全部字段可选：

{
    "headers": { "X-Custom": "value" },
    "tmp_dir": "/tmp/wecom-custom"
}

字段	作用
headers	额外请求头（别名 additional_headers）
tmp_dir	覆盖临时目录根目录

说明：

• 环境变量优先级高于配置文件。
• access token 不允许经 config.json 配置，仅来自 credentials.enc。

退出码与错误格式

退出码	含义
0	成功（含 --help / --version）
1	运行时错误（网络、鉴权、IO、后台业务错误等）
2	用法错误（参数缺失、未知命令等；后台返回用法类错误码时也会渲染当前命令 help）

错误以结构化 JSON 输出到 stdout：

{
    "error": {
        "type": "AuthError",
        "code": 893201,
        "message": "..."
    }
}

• CLI 自身错误的 code 段：893000–893099（lib）、893100–893199（transport）、893200–893299（bin），893999 为共享兜底码。
• 后台业务错误（errcode != 0）直接透传后台响应体与原 errcode。
• 日志与提示信息一律走 stderr，不污染 stdout 的 JSON 输出。