feishu-cli-api

name	feishu-cli-api
description	飞书 OpenAPI 裸调。api GET/POST/PUT/DELETE/PATCH <path> 直接调用任意飞书 OpenAPI 接口， 覆盖 feishu-cli 尚未封装的接口（对齐 lark-cli 的 api 能力）。支持 --params(query)/--data(body JSON)/--data-file(从文件读 body)/ --as auto|user|bot 身份/--dry-run 预览/-o 二进制下载/--format/--jq。 当用户请求"调用 X API"、"裸调飞书接口"、"feishu-cli 没封装的接口怎么调"、"raw api"、 "用 api 命令发请求"、"下载飞书媒体/文件 binary"时使用。 不适用：仅查 schema 不调用（用 feishu-cli schema）；已有专用命令的高频场景（用对应 feishu-cli <模块>）。
argument-hint	<METHOD> <path>
user-invocable	true
allowed-tools	Bash(feishu-cli api:*), Bash(feishu-cli schema:*), Read

飞书 OpenAPI 裸调技能

feishu-cli api 直接调用任意飞书 OpenAPI 接口，覆盖尚未封装成专用命令的接口。是单工具栈下替代 lark-cli api 的兜底能力。

feishu-cli：如尚未安装，请前往 riba2534/feishu-cli 获取安装方式。

---

用法

feishu-cli api <METHOD> <path> [flags]

• METHOD：GET | POST | PUT | DELETE | PATCH（大小写不敏感）
• path：完整 API 路径，如 /open-apis/im/v1/messages（前导斜杠可省略；误传完整 URL 会自动剥掉 host）

Flags

Flag	说明
--params '<json>'	query 参数（JSON 对象），如 '{"page_size":10}'
--data '<json>' / --data-file <file>	请求体：--data 传 JSON 字符串，或 --data-file 从文件读（- 表示 stdin）；二者互斥
--as auto|user|bot	身份：auto（User 优先 Tenant 兜底，默认）/ user（强制 User Token，需先 auth login）/ bot（强制 Tenant/应用 Token）
--user-access-token	显式传 User Access Token（--as user/auto 时用）
--dry-run	只打印将发送的请求（method/path/query/body/identity），不实际调用
-o <file>	写原始响应体到文件（binary-safe，适合下载类接口）
--format json|pretty|table|ndjson|csv	响应渲染格式（指定后走内置渲染，覆盖默认 pretty；仅适用于 JSON 响应）
--jq '<expr>'	用内置 gojq 过滤响应（无需外部 jq；仅适用于 JSON 响应）

-o 二进制下载 与 --format/--jq 互斥：默认 / --raw / 纯 -o 走原样写文件路径（binary-safe）；一旦带上 --format 或 --jq，响应会先按 JSON 解析再渲染，二进制响应会 decode 失败并报错「响应不是合法 JSON，无法用 --format/--jq 渲染（去掉这两个 flag 可用 --raw 原样输出）」。下载媒体/文件时只用 -o，不要叠加 --format/--jq。

大整数精度：响应用 UseNumber 解析，飞书 19 位 message_id/chat_id 等不会被降级丢精度。

---

三步调研法（不知道 path 时）

feishu-cli schema <service>                 # 1. 列出该 service 的 resource.method
feishu-cli schema <service>.<resource>.<method>   # 2. 查 path / 参数 / scope
feishu-cli api <METHOD> <path> ...          # 3. 裸调

---

示例

# GET + query + jq 过滤
feishu-cli api GET /open-apis/wiki/v2/spaces --params '{"page_size":10}' --jq '.data.items[].name'

# POST 发消息（先 dry-run 预览）
feishu-cli api POST /open-apis/im/v1/messages \
  --params '{"receive_id_type":"chat_id"}' \
  --data '{"receive_id":"oc_xxx","msg_type":"text","content":"{\"text\":\"hi\"}"}' --dry-run

# 请求体从文件读
feishu-cli api POST /open-apis/bitable/v1/apps/xxx/tables --data-file body.json

# 下载二进制到文件
feishu-cli api GET /open-apis/drive/v1/medias/<token>/download -o /tmp/file.bin

# 强制用户身份（访问用户私有资源）
feishu-cli api GET /open-apis/calendar/v4/calendars --as user

# 表格输出
feishu-cli api GET /open-apis/wiki/v2/spaces --jq '.data.items' --format table

---

何时用专用命令而非 api

api 是兜底。高频场景优先用封装好的专用命令（错误处理/参数校验/便捷 flag 更完善）：消息→msg、文档→doc、多维表格→bitable、表格→sheet、日历→calendar 等。仅当某接口没有对应专用命令时用 api 裸调。