企业微信命令行工具

Project description

WeCom CLI

企业微信命令行工具，支持多级命令结构。

安装

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

使用

全局选项

所有命令都支持 --json 选项，用于以 JSON 格式输出结果：

# JSON 输出
wecom-cli --json version
wecom-cli --json config get auth.corpid
wecom-cli --json doc list

# 默认输出（带格式化）
wecom-cli version
wecom-cli config get auth.corpid
wecom-cli doc list

查看帮助

wecom-cli --help

配置管理

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

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

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

# JSON 输出
wecom-cli --json config get auth

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

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

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

键路径语法：

使用点 . 分隔嵌套键，如 auth.corpid
键路径不能为空、不能以点开头或结尾、不能有连续的点

JSON 值：

使用 --json 标志指示值为 JSON 格式
支持所有 JSON 数据类型：字符串、数字、布尔值、null、数组、对象
JSON 格式错误时会显示友好的错误信息

注意：

配置文件存储在 ~/.config/wecom-cli/config.toml，文件权限为 600（仅用户可读写）
token 会自动缓存并在过期前 5 分钟自动刷新
代理为可选配置，未配置时直连企微 API
代理 URL 必须以 http:// 或 https:// 开头
如果同时配置 HTTP 和 HTTPS 代理，优先使用 HTTPS 代理
敏感信息在显示时自动脱敏（如 apiKey、corpsecret 等）

文档管理

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

# JSON 输出
wecom-cli --json doc add --name "文档名称" --type doc

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

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

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

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

# JSON 输出
wecom-cli --json doc list

智能表格子表操作

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

# JSON 输出
wecom-cli --json doc smart sheet add --name "文档名称" --title "子表标题"

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

# JSON 输出
wecom-cli --json doc smart sheet delete --name "文档名称" --sheet-id "123abc"

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

# JSON 输出
wecom-cli --json doc smart sheet update --name "文档名称" --sheet-id "123abc" --title "新标题"

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

# JSON 输出
wecom-cli --json doc smart sheet query --name "文档名称" --sheet-id "123abc"

参数说明：

--docid：直接提供文档 ID
--name：通过文档名称从注册表查找文档 ID（与 --docid 二选一）
--title：子表标题（add/update 命令必填）
--index：子表位置（add 命令可选，不指定则添加到末尾）
--sheet-id：子表 ID（delete/update/query 命令必填）

智能表格字段操作

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

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

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

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

# 更新字段
wecom-cli doc smart field update --docid "DOCID" --sheet-id "s1" \
  --field-id "fld1" --title "新名称" --type FIELD_TYPE_TEXT
wecom-cli doc smart field update --docid "DOCID" --sheet-id "s1" \
  --field-id "fld2" --type FIELD_TYPE_NUMBER \
  --property 'property_number={"decimal_places":3}'

# JSON 输出
wecom-cli --json doc smart field add --docid "DOCID" --sheet-id "s1" \
  --title "名称" --type FIELD_TYPE_TEXT

字段类型：

FIELD_TYPE_TEXT, FIELD_TYPE_NUMBER, FIELD_TYPE_CHECKBOX, FIELD_TYPE_DATE_TIME
FIELD_TYPE_IMAGE, FIELD_TYPE_ATTACHMENT, FIELD_TYPE_USER, FIELD_TYPE_URL
FIELD_TYPE_SELECT, FIELD_TYPE_SINGLE_SELECT, FIELD_TYPE_PROGRESS
FIELD_TYPE_PHONE_NUMBER, FIELD_TYPE_EMAIL, FIELD_TYPE_LOCATION
FIELD_TYPE_CURRENCY, FIELD_TYPE_PERCENTAGE, FIELD_TYPE_BARCODE
FIELD_TYPE_CREATED_USER, FIELD_TYPE_MODIFIED_USER
FIELD_TYPE_CREATED_TIME, FIELD_TYPE_MODIFIED_TIME
FIELD_TYPE_REFERENCE, FIELD_TYPE_WWGROUP, FIELD_TYPE_AUTONUMBER

字段属性格式：--property 属性名=JSON值

示例：--property 'property_number={"decimal_places":2}'
示例：--property 'property_select={"options":[{"text":"选项1","style":1}]}'

智能表格记录操作

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

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

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

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

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

# 查询指定记录
wecom-cli doc smart record query --docid "DOCID" --sheet-id "s1" \
  --record-id "rec1"

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

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

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

# JSON 输出
wecom-cli --json doc smart record query --docid "DOCID" --sheet-id "s1"

记录过滤查询（filter_spec）

查询记录支持通过 --filter 选项传入过滤条件，每个 --filter 是一个 JSON 格式的 Condition，多个条件通过 --filter-conjunction 指定 AND 或 OR 组合。

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

# 数字大于筛选
wecom-cli doc smart record query --docid "DOCID" --sheet-id "s1" \
  --filter '{"field_id":"f2","field_type":"FIELD_TYPE_NUMBER","operator":"OPERATOR_IS_GREATER","number_value":{"value":10}}'

# 日期为今天
wecom-cli doc smart record query --docid "DOCID" --sheet-id "s1" \
  --filter '{"field_id":"f3","field_type":"FIELD_TYPE_DATE_TIME","operator":"OPERATOR_IS","date_time_value":{"type":"DATE_TIME_TYPE_TODAY"}}'

# 为空判断
wecom-cli doc smart record query --docid "DOCID" --sheet-id "s1" \
  --filter '{"field_id":"f4","field_type":"FIELD_TYPE_TEXT","operator":"OPERATOR_IS_EMPTY"}'

# 多条件 AND 组合（默认）
wecom-cli doc smart record query --docid "DOCID" --sheet-id "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 "DOCID" --sheet-id "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"]}}'

支持的操作符：

OPERATOR_IS（等于）、OPERATOR_IS_NOT（不等于）
OPERATOR_CONTAINS（包含）、OPERATOR_DOES_NOT_CONTAIN（不包含）
OPERATOR_IS_GREATER（大于）、OPERATOR_IS_GREATER_OR_EQUAL（大于或等于）
OPERATOR_IS_LESS（小于）、OPERATOR_IS_LESS_OR_EQUAL（小于或等于）
OPERATOR_IS_EMPTY（为空）、OPERATOR_IS_NOT_EMPTY（不为空）

值类型：

string_value：文本/网址/电话/邮箱/单选/多选 - {"value":["文本值"]}
number_value：数字/进度 - {"value": 123}
bool_value：复选框 - {"value": true}
user_value：人员/创建人/编辑人 - {"value": ["成员ID"]}
date_time_value：日期 - {"type":"DATE_TIME_TYPE_TODAY"} 或 {"type":"DATE_TIME_TYPE_DETAIL_DATE","value":["1715846245084"]}

日期类型：

DATE_TIME_TYPE_DETAIL_DATE（具体时间，需提供毫秒时间戳）
DATE_TIME_TYPE_TODAY, DATE_TIME_TYPE_TOMORROW, DATE_TIME_TYPE_YESTERDAY
DATE_TIME_TYPE_CURRENT_WEEK, DATE_TIME_TYPE_LAST_WEEK, DATE_TIME_TYPE_CURRENT_MONTH
DATE_TIME_TYPE_THE_PAST_7_DAYS, DATE_TIME_TYPE_THE_NEXT_7_DAYS
DATE_TIME_TYPE_LAST_MONTH, DATE_TIME_TYPE_THE_PAST_30_DAYS, DATE_TIME_TYPE_THE_NEXT_30_DAYS

注意：--filter 不支持和 --sort 同时使用。

版本信息

wecom-cli version

# JSON 输出
wecom-cli --json version

项目结构

wecom-cli/
├── src/
│   └── wecom_cli/
│       ├── __init__.py
│       ├── cli.py                 # 主CLI入口
│       ├── config.py              # 配置文件管理（TOML）
│       ├── doc_registry.py        # 文档注册表
│       ├── output.py              # 输出工具模块
│       ├── api/                   # 企业微信 API 封装
│       │   ├── client.py          # HTTP 客户端
│       │   ├── auth.py            # Token 管理
│       │   └── doc.py             # 文档/子表/字段/记录 API
│       └── commands/
│           ├── config/            # 配置管理命令
│           │   └── config_app.py
│           └── doc/
│               ├── doc_app.py      # doc命令入口
│               ├── add.py          # add命令实现
│               ├── delete.py       # delete命令实现
│               ├── rename.py       # rename命令实现
│               ├── share.py        # share命令实现
│               └── smart/
│                   ├── smart_app.py
│                   ├── create.py   # create命令实现
│                   ├── field/      # 字段操作命令
│                   │   ├── field_app.py
│                   │   ├── add.py
│                   │   ├── delete.py
│                   │   ├── update.py
│                   │   └── query.py
│                   ├── record/     # 记录操作命令
│                   │   ├── record_app.py
│                   │   ├── add.py
│                   │   ├── delete.py
│                   │   ├── update.py
│                   │   └── query.py
│                   └── sheet/      # 子表操作命令
│                       ├── sheet_app.py
│                       ├── add.py
│                       ├── delete.py
│                       ├── update.py
│                       └── query.py
├── tests/
│   ├── test_config.py
│   ├── test_client.py
│   ├── test_auth.py
│   ├── test_config_commands.py
│   ├── test_cli.py
│   ├── test_output.py
│   ├── test_cli_json.py
│   ├── test_doc_json.py
│   ├── test_api_doc.py
│   ├── test_api_field_record.py
│   ├── test_field_commands.py
│   └── test_record_commands.py
├── pyproject.toml
├── README.md
└── .gitignore

开发

# 安装依赖
uv sync

# 运行 CLI（开发环境）
uv run wecom-cli --help

# 运行测试
uv run pytest

# 代码检查
uv run ruff check .

# 代码格式化
uv run ruff format .

技术栈

Python 3.12+
Typer（CLI 框架）
Rich（终端输出）
httpx（HTTP 客户端）
pytest（测试）
ruff（代码检查与格式化）

开发流程

详见 AGENTS.md

Project details

Release history Release notifications | RSS feed

0.1.21

May 6, 2026

0.1.2

Apr 24, 2026

0.1.1

Apr 23, 2026

This version

0.1.0

Apr 23, 2026

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

wecom_cli-0.1.0.tar.gz (146.8 kB view details)

Uploaded Apr 23, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

wecom_cli-0.1.0-py3-none-any.whl (39.9 kB view details)

Uploaded Apr 23, 2026 Python 3

File details

Details for the file wecom_cli-0.1.0.tar.gz.

File metadata

Download URL: wecom_cli-0.1.0.tar.gz
Upload date: Apr 23, 2026
Size: 146.8 kB
Tags: Source
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.2.0 CPython/3.12.13

File hashes

Hashes for wecom_cli-0.1.0.tar.gz
Algorithm	Hash digest
SHA256	`06179d337b5611877a1916c0b74ec51f999fb43fda3e92b97ada40d75d43f190`
MD5	`6618763f9b3c0b1baf9a64e0ef83a97a`
BLAKE2b-256	`c64b85804bb7576d1b5ab6ad3ba4ebbb476067fedeb764b404d2e5a25a30b70a`

See more details on using hashes here.

File details

Details for the file wecom_cli-0.1.0-py3-none-any.whl.

File metadata

Download URL: wecom_cli-0.1.0-py3-none-any.whl
Upload date: Apr 23, 2026
Size: 39.9 kB
Tags: Python 3
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.2.0 CPython/3.12.13

File hashes

Hashes for wecom_cli-0.1.0-py3-none-any.whl
Algorithm	Hash digest
SHA256	`3c432aa9d3d65009994a00670148c476c003a028b71d670b98c2a44f17f50ffe`
MD5	`4042b94a8d22f3e490bc39da2ecf6e3e`
BLAKE2b-256	`adccf379f2ba32dfaeb541fba6ad7078cabd85251e7a2841be7fc1560970de10`

See more details on using hashes here.

wecom-cli 0.1.0

Navigation

Verified details

Maintainers

Unverified details

Meta

Project description

WeCom CLI

安装

使用

全局选项

查看帮助

配置管理

文档管理

智能表格子表操作

智能表格字段操作

智能表格记录操作

记录过滤查询（filter_spec）

版本信息

项目结构

开发

技术栈

开发流程

Project details

Verified details

Maintainers

Unverified details

Meta

Release history Release notifications | RSS feed

Download files

Source Distribution

Built Distribution

File details

File metadata

File hashes

File details

File metadata

File hashes