feishu-cli-api 是 feishu-cli 提供的飞书 OpenAPI 裸调技能，用于直接调用任意飞书 OpenAPI 接口，覆盖 feishu-cli 尚未封装成专用命令的接口，是在单工具栈下替代 lark-cli api 的兜底能力。
用途与定位
feishu-cli api 是兜底能力。高频场景应优先使用封装好的专用命令，因为它们在错误处理、参数校验和便捷 flag 上更完善，例如消息对应 msg、文档对应 doc、多维表格对应 bitable、表格对应 sheet、日历对应 calendar 等。仅当某接口没有对应专用命令时，才使用 api 裸调。
基本用法
feishu-cli api <METHOD> <path> [flags]
METHOD：GET | POST | PUT | DELETE | PATCH，大小写不敏感。
path：完整 API 路径，例如 /open-apis/im/v1/messages；前导斜杠可省略；如果误传完整 URL，会自动剥掉 host。
如果尚未安装 feishu-cli，文档提示前往 riba2534/feishu-cli 获取安装方式。
Flags 说明
--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 或 --as 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>：列出该 service 的 resource.method。
-
feishu-cli schema <service>.<resource>.<method>：查看 path、参数、scope。
-
feishu-cli api <METHOD> <path> ...：执行裸调。
示例
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
适用场景与限制
适用于飞书 OpenAPI 中尚无专用命令的接口调用、临时调研接口、需要直接控制 method/path/query/body 的场合，以及需要二进制下载或 jq 过滤输出的场景。限制方面：它是兜底手段而非首选；--format/--jq 仅适用于 JSON 响应，且与 -o 二进制下载互斥；下载文件时应仅使用 -o。User 身份需先完成 auth login。