wecom-cli 0.1.21

企业微信命令行工具

WeCom CLI

企业微信命令行工具，支持多级命令结构。既可作为 CLI 使用，也可作为 Python 库导入。

安装

cd wecom-cli
uv sync
source .venv/bin/activate

使用

全局约定

• 所有命令都支持 --json/-j 参数，以 JSON 格式输出结果
• 文档操作可通过 --docid/-d 或 --name/-n 指定文档（二选一）
• 纯文本输出，便于 LLM 阅读和管道处理

Python 库使用

from wecom_cli.api.auth import get_access_token
from wecom_cli.api.doc.mng import create_doc
from wecom_cli.api.doc.smart.record import get_records

token = get_access_token()
result = create_doc(token, doc_type=10, doc_name="我的文档")
records = get_records(token, docid="DOC_ID", sheet_id="SHEET_ID",
                       key_type="CELL_VALUE_KEY_TYPE_FIELD_TITLE")

自定义配置文件路径

from wecom_cli.config.config import init_config, reset_config

# 指定自定义配置文件路径（文件不存在时自动创建含 auth + proxy 空模板）
init_config("/path/to/my-config.toml")

# 后续所有配置操作（包括 auth、registry）自动使用该路径
from wecom_cli.api.auth import get_access_token
token = get_access_token()

# 重置为默认配置路径
reset_config()

查看帮助

wecom-cli --help

配置管理

# 初始化配置
wecom-cli config init

# 设置字符串值
wecom-cli config set auth.corpid 'wwa'

# 设置 JSON 值
wecom-cli config set b.a --json-value/-J '{
  "a": 1,
  "b": 2
}'

# 获取配置项
wecom-cli config get auth.corpid

# JSON 输出
wecom-cli config get auth.corpid -j

# 显示所有配置
wecom-cli config show

# 列出所有配置项
wecom-cli config list

# 删除配置项
wecom-cli config set auth.corpid ""
wecom-cli config set auth.corpid --json-value "null"

# 查看 Token 状态
wecom-cli config token

# 代理配置
wecom-cli config proxy --http http://proxy:8080 --https https://proxy:8443

文档管理

# 创建文档
wecom-cli doc add --name/-n "文档名称" --type/-t doc

# 删除文档
wecom-cli doc delete --name/-n "文档名称"

# 重命名文档
wecom-cli doc rename --name/-n "旧名称" --new-name/-N "新名称"

# 获取分享链接
wecom-cli doc share --name/-n "文档名称"

# 列出所有文档
wecom-cli doc list

# JSON 输出
wecom-cli doc list -j

智能表格子表操作

# 添加子表
wecom-cli doc smart sheet add --name/-n "文档名称" --title/-t "子表标题"
wecom-cli doc smart sheet add --docid/-d "DOCID" --title/-t "子表标题" --index/-i 3

# 删除子表
wecom-cli doc smart sheet delete --name/-n "文档名称" --sheet-id/-s "123abc"

# 更新子表标题
wecom-cli doc smart sheet update --name/-n "文档名称" --sheet-id/-s "123abc" --title/-t "新标题"

# 查询子表信息
wecom-cli doc smart sheet query --name/-n "文档名称" --sheet-id/-s "123abc"

智能表格字段操作

# 添加字段
wecom-cli doc smart field add --docid/-d "DOCID" --sheet-id/-s "s1" \
  --title/-t "名称" --type/-T FIELD_TYPE_TEXT

# 添加带属性的字段
wecom-cli doc smart field add --docid/-d "DOCID" --sheet-id/-s "s1" \
  --title/-t "数量" --type/-T FIELD_TYPE_NUMBER \
  --property/-p 'property_number={"decimal_places":2,"use_separate":true}'

# 删除字段
wecom-cli doc smart field delete --docid/-d "DOCID" --sheet-id/-s "s1" \
  --field-id/-f "fld1" --field-id/-f "fld2"

# 查询字段
wecom-cli doc smart field query --docid/-d "DOCID" --sheet-id/-s "s1"
wecom-cli doc smart field query --docid/-d "DOCID" --sheet-id/-s "s1" \
  --field-id/-f "fld1" --offset/-o 0 --limit/-l 10

# 更新字段
wecom-cli doc smart field update --docid/-d "DOCID" --sheet-id/-s "s1" \
  --field-id/-f "fld1" --title/-t "新名称" --type/-T FIELD_TYPE_TEXT

智能表格记录操作

# 添加记录
wecom-cli doc smart record add --docid/-d "DOCID" --sheet-id/-s "s1" \
  --record/-r '{"values":{"名称":[{"type":"text","text":"测试"}]}}'

# 添加多条记录
wecom-cli doc smart record add --docid/-d "DOCID" --sheet-id/-s "s1" \
  --record/-r '{"values":{"名称":[{"type":"text","text":"记录1"}]}}' \
  --record/-r '{"values":{"名称":[{"type":"text","text":"记录2"}]}}'

# 使用字段 ID 作为 key
wecom-cli doc smart record add --docid/-d "DOCID" --sheet-id/-s "s1" \
  --key-type/-k CELL_VALUE_KEY_TYPE_FIELD_ID \
  --record/-r '{"values":{"fld1":[{"type":"text","text":"测试"}]}}'

# 删除记录
wecom-cli doc smart record delete --docid/-d "DOCID" --sheet-id/-s "s1" \
  --record-id/-r "rec1" --record-id/-r "rec2"

# 查询记录
wecom-cli doc smart record query --docid/-d "DOCID" --sheet-id/-s "s1"

# 分页查询
wecom-cli doc smart record query --docid/-d "DOCID" --sheet-id/-s "s1" \
  --offset/-o 0 --limit/-l 100

# 自动分页获取全部记录
wecom-cli doc smart record query --docid/-d "DOCID" --sheet-id/-s "s1" --all/-a

# 自动分页 + JSON 输出
wecom-cli doc smart record query --docid/-d "DOCID" --sheet-id/-s "s1" --all/-a -j

# 排序查询
wecom-cli doc smart record query --docid/-d "DOCID" --sheet-id/-s "s1" \
  --sort '{"field_title":"名称","desc":true}'

# 更新记录
wecom-cli doc smart record update --docid/-d "DOCID" --sheet-id/-s "s1" \
  --record/-r '{"record_id":"rec1","values":{"名称":[{"type":"text","text":"新值"}]}}'

记录过滤查询（filter_spec）

# 文本包含筛选
wecom-cli doc smart record query --docid/-d "DOCID" --sheet-id/-s "s1" \
  --filter '{"field_id":"f1","field_type":"FIELD_TYPE_TEXT","operator":"OPERATOR_CONTAINS","string_value":{"value":["hello"]}}'

# 多条件 AND 组合（默认）
wecom-cli doc smart record query --docid/-d "DOCID" --sheet-id/-s "s1" \
  --filter '{"field_id":"f1","field_type":"FIELD_TYPE_TEXT","operator":"OPERATOR_CONTAINS","string_value":{"value":["hello"]}}' \
  --filter '{"field_id":"f2","field_type":"FIELD_TYPE_NUMBER","operator":"OPERATOR_IS_GREATER","number_value":{"value":10}}'

# 多条件 OR 组合
wecom-cli doc smart record query --docid/-d "DOCID" --sheet-id/-s "s1" \
  --filter-conjunction CONJUNCTION_OR \
  --filter '{"field_id":"f1","field_type":"FIELD_TYPE_TEXT","operator":"OPERATOR_IS","string_value":{"value":["A"]}}' \
  --filter '{"field_id":"f1","field_type":"FIELD_TYPE_TEXT","operator":"OPERATOR_IS","string_value":{"value":["B"]}}'

版本信息

wecom-cli version
wecom-cli version -j

参数短选项速查表

参数	短选项	说明
--json	-j	JSON 格式输出
--docid	-d	文档 ID
--name	-n	文档名称
--sheet-id	-s	子表 ID
--field-id	-f	字段 ID
--field-title	-F	字段标题
--title	-t	标题
--type	-T	类型
--record-id	-r	记录 ID
--record	-r	记录 JSON
--key-type	-k	Key 类型
--offset	-o	偏移量
--limit	-l	分页大小
--property	-p	属性
--filter	无	过滤条件
--all	-a	获取全部
--new-name	-N	新名称
--index	-i	位置索引
--admin	-a	管理员
--http	-h	HTTP 代理
--https	-S	HTTPS 代理
--json-value	-J	JSON 值
--all-type	-A	所有类型

技术栈

• Python 3.12+
• Typer（CLI 框架）
• httpx（HTTP 客户端）
• tomli-w（TOML 写入）
• pytest（测试）
• ruff（代码检查与格式化）

开发

uv sync
uv run wecom-cli --help
uv run pytest
uv run ruff check .
uv run ruff format .

开发流程

详见 AGENTS.md