gem-hunter
Language: Go
feishu-cli 是一个功能完整的飞书开放平台命令行工具。它将飞书文档、知识库、电子表格、消息、日历、任务等操作封装为简洁的命令行接口，核心能力是 Markdown ↔ 飞书文档双向无损转换。
飞书开放平台命令行工具 — Markdown 与飞书文档双向转换，AI Agent 的飞书操控引擎
介绍 · 30 秒上手 · 核心能力 · 快速开始 · 命令参考 · AI 技能 · FAQ · 更新日志
feishu-cli 是一个功能完整的飞书开放平台命令行工具。它将飞书文档、知识库、电子表格、消息、日历、任务等操作封装为简洁的命令行接口，核心能力是 Markdown ↔ 飞书文档双向无损转换。
除了传统的 CLI 用法，feishu-cli 还为 Claude Code 等 AI 编程助手提供了 9 个开箱即用的领域技能（Skill），让 AI Agent 能够直接创建文档、发送消息、管理权限——无需任何额外配置。
注意：feishu-cli 主要面向 AI Agent（如 Claude Code）使用，通过技能文件让 AI 直接操控飞书。虽然人类也可以直接使用命令行，但大多数场景下建议通过 AI Agent 调用，体验更佳。
msg history --user-email 一条命令打通「搜用户 → 反查 p2p chat_id → 读消息」，输出自动带 sender_names 映射，AI Agent 直接拿结构化带名消息流，无需额外查群成员--dry-run、幂等键防重发、统一 --jq/--format 结构化输出# 1. 安装（自动识别平台，含 sha256 完整性校验） curl -fsSL https://raw.githubusercontent.com/riba2534/feishu-cli/main/install.sh | bash # 2. 一键创建飞书应用并保存凭证（Device Flow，免手工建应用） feishu-cli config create-app --save # 3. 把 Markdown 变成飞书文档 feishu-cli doc import README.md --title "我的第一篇文档"
需要用户身份的能力（搜索、审批、邮箱等）再执行 feishu-cli auth login 完成 OAuth 授权即可。详见快速开始。
将本地 Markdown 文件一键上传到飞书，或将飞书文档导出为 Markdown。支持完整语法转换：
# 导入：Markdown → 飞书文档 feishu-cli doc import report.md --title "技术报告" --verbose # 导出：飞书文档 → Markdown feishu-cli doc export <document_id> -o doc.md --download-images
支持的语法：标题（6 级）、段落、列表（无限深度嵌套）、任务列表、代码块、引用、Callout（6 种类型）、同步块（含跨文档引用）、表格（自动拆分）、分割线、图片、链接、公式、粗体 / 斜体 / 删除线 / 下划线 / 行内代码（<mark> 高亮暂以下划线近似）。跨文档同步块无法读取时会保留带源标识的 WARNING 占位并输出诊断，不会静默导出为空。
Markdown 中的 Mermaid 和 PlantUML 代码块自动转换为飞书画板（可编辑矢量图，非截图）：
```mermaid flowchart TD A[开始] --> B{判断} B -->|是| C[处理] B -->|否| D[结束] ```
| 图表类型 | 声明 | 说明 |
|---|---|---|
| 流程图 | flowchart TD / flowchart LR |
支持 subgraph |
| 时序图 | sequenceDiagram |
参与者建议 ≤ 8 |
| 类图 | classDiagram |
|
| 状态图 | stateDiagram-v2 |
必须用 v2 |
| ER 图 | erDiagram |
|
| 甘特图 | gantt |
|
| 饼图 | pie |
|
| 思维导图 | mindmap |
PlantUML 同样支持：时序图、活动图、类图、用例图、组件图、ER 图、思维导图等全部类型（```plantuml 或 ```puml）。
大规模实测导入成功率 >90%，失败图表自动降级为代码块并保留原文，不阻断整篇导入。
<!-- feishu-colwidth: 80,200,*,30% -->（单位 px / 百分比 / * 走 auto）或 CLI flag --table-column-width=auto|fixed|N1,N2,... 全局覆盖；注释优先级高于 flag。仅 doc import / doc add 支持——doc content-update 走官方原子更新协议不支持自定义列宽，传非 auto 的 flag 或内容含该注释都会报错create_block 9 行限制时，先创建 9 行初始表，剩余行通过 insert_table_row API 追加到同一个 block，视觉上为一张连贯的表，不再拆成多张独立表格batch_update API（每批 ≤30）+ 文档级 3 QPS 节流，典型 4×6×8 表场景从 ~70s 降到 ~3s导入大文档时，feishu-cli 使用三阶段并发管道最大化吞吐量：
feishu-cli doc import large-doc.md --title "大文档" \
--upload-images --diagram-workers 5 --table-workers 3 --image-workers 2 --verbose| 模块 | 能力 |
|---|---|
| 文档 | 创建（带本地图片/附件/HTML 块/画板源文件）、导入、导出、大文档选择性读取（doc read：大纲/按标题取节/关键词定位，可转成直接发 IM 的 Markdown）、编辑、批量更新、Callout、画板、文档封面、素材插入/下载/预览、写作草稿与 DocxXML 预检（doc script）、异步导出/导入文件 |
| 思维笔记 | 读取已有思维笔记的节点、新增子节点或更新节点（mindnote nodes list/create） |
| 知识库 | 空间列表、节点增删改查、导出（含整树递归镜像）、移出知识库到云盘（move-to-drive）、空间详情、成员管理 |
| 电子表格 | V2 基础读写 + V3 富文本 API，行列操作、样式、批量样式、合并、查找替换、导出 XLSX/CSV、浮动图片读写、素材上传、单元格写图、筛选视图与筛选条件 CRUD、下拉菜单数据验证、类型保真整表读写 table-get/table-put（数字/日期/布尔 dtype 保真，支持 get→改→put round-trip） |
| 多维表格 | base/v3 + bitable/v1 全覆盖：数据表/字段/记录 CRUD（含批量获取）、记录附件上传/下载/移除、视图配置（filter/sort/group/visible-fields/timebar/card）、仪表盘 CRUD 与智能排版、仪表盘块 CRUD、表单 CRUD 与分享详情/提交、表单问题 CRUD、角色 CRUD 与协作者管理、高级权限、数据聚合、工作流 CRUD、多维表格重命名与权限设置 |
| 消息 | 发送与回复共用 text/Markdown/post/image/file/audio/video/card 内容模型（本地媒体自动上传、幂等键）、转发、合并转发、Pin、表情回复、消息书签（flag create/list/cancel）、搜索群聊（Bot/User 双身份）、历史记录（群聊 / P2P 私聊，支持 --user-email / --user-id 自动反查 p2p chat_id）、批量获取、资源下载、话题回复、发送者名字自动解析（输出顶层 sender_names 映射，覆盖退群成员） |
| 群聊 | 创建、获取、更新、删除、分享链接、成员管理、群列表（chat list，--page-all 全量拉取 + 安全截断告警） |
| 邮箱 | 收件箱分类/搜索、邮件详情（单条/批量/线程）、发送（默认草稿，支持 CID 内联图片自动扫描）、草稿管理（创建/编辑/发送已有草稿）、回复/全部回复/转发、批量改 label/移动文件夹、批量软删进废纸篓、邮件模板 create/list、邮箱签名查看（需 User Token） |
| 日历 | 日历列表、主日历、日程增删改查、搜索、回复邀请、参与者管理、忙闲查询、日程视图（agenda）、智能时段建议、会议室查找、RSVP |
| 任务 | 创建、查看、完成、重新打开、服务端搜索（按创建者/执行者/关注者/完成态/截止时间）、子任务、成员管理、提醒、评论、附件上传、我的任务、任务清单（CRUD + 任务关联 + 成员管理） |
| 视频会议 | 多维搜索（query/主持人/参会者/会议室）、聚合详情（vc detail：会议信息 + note_id + minute_token 一次拿齐，支持会议号反查）、智能纪要（vc note：详情 / 统一逐字稿导出）、会议纪要（三路径批量获取 + AI 产物 + 逐字稿下载）、录制查询、会议机器人入会/离会/会议事件（--as bot|user|auto） |
| 妙记 | 详情 + AI 产物、关键词搜索、权限申请、等待转写就绪（--wait-ready）、媒体批量下载 |
| 审批 | 审批定义与实例详情查询、当前登录用户审批任务查询（待办 / 已办 / 已发起 / 抄送）、发起/撤回/抄送审批实例、通过/拒绝/转交审批任务 |
| 考勤 | 查询用户打卡记录与日/月度考勤统计（tenant token，日期范围最长 31 天） |
| OKR | 周期列表/详情（目标 + 关键结果）、进展记录 CRUD、进展图片上传、`--as bot |
| 权限 | 添加 / 更新 / 删除协作者、批量添加、公开权限管理、分享密码、权限检查、转移所有权 |
| 云盘增强 | 大文件分块上传（>20MB 自动分片）、原地覆盖上传（--file-token）、流式下载、异步导出（docx→markdown 快捷路径 + sheet/bitable CSV）、异步导入、文件夹移动（自动轮询）、富文本评论（wiki URL 解析）、异步任务查询、URL 解析 inspect、权限申请、本地镜像 pull/push/status、v2 搜索、密级标签查询/设置 |
| 原生 Markdown 文件 | Drive .md 文件 create/fetch/overwrite，整体保留 Markdown 源码，不转换为飞书 docx 块；本地比对远端最新与历史版本 |
| 文件 | 云空间文件列表、创建、移动、复制、删除、上传、下载、版本管理（含回滚到历史版本）、元数据、统计 |
| 素材 | 上传 / 下载（图片、文件、音视频） |
| 画板 | 精排绘图（create-notes）、Mermaid / PlantUML 导入、克隆（connector 重映射）、几何质检 lint、SVG 双向（svg-import / svg-export / export-code）、图片上传、覆盖更新（含快照）、截图下载、节点管理 |
| Slides | 创建空白演示文稿、上传媒体到演示文稿 |
| 评论 | 列出、添加、解决/恢复评论、回复管理 |
| 搜索 | 消息搜索（默认返回消息 ID，--enrich 补全内容/发送者/群名/时间）、应用搜索、文档搜索（需 User Access Token） |
| 用户 | 获取用户信息、用户搜索、部门用户列表 |
| 通讯录 | 部门详情、子部门列表 |
| 实时事件 | WebSocket 长连接订阅应用事件（EventKey 列表/schema/consume/status/stop），卡片按钮/表单回调（card.action.trigger）、审批 v4 事件（自动注册服务端订阅）、VC participant/note/recording 事件（User pre-consume，握手后 ready）、Bot 菜单事件 |
| Raw API | api GET/POST/PUT/DELETE/PATCH <path> 裸调任意未封装的 OpenAPI 接口，自动鉴权与错误码处理，支持 dry-run、自定义超时、jq 过滤与 json/pretty/table/ndjson/csv 多格式输出 |
| OpenAPI Schema | 本地查询内置 OpenAPI service/resource/method、路径、参数和 scope，无需 token |
| Profile 多配置 | 多 App / 多账号配置 add/list/use/current/rename/remove/migrate；profile list --json 列出可操作 Bot；全局 --profile / FEISHU_PROFILE 单次切换目录与 User Token（FEISHU_APP_ID/SECRET 仍可覆盖 App 凭证） |
| 健康检查 | doctor 一次检查配置、User Token、端点、代理和本地依赖 |
一键安装（推荐）
自动检测平台，下载最新版本并安装到 /usr/local/bin：
curl -fsSL https://raw.githubusercontent.com/riba2534/feishu-cli/main/install.sh | bash已安装的用户执行同样的命令即可更新到最新版本。
其他安装方式手动下载
从 Releases 页面下载对应平台的压缩包：
| 平台 | 文件 |
|---|---|
| Linux x64 | feishu-cli_*_linux-amd64.tar.gz |
| Linux ARM64 | feishu-cli_*_linux-arm64.tar.gz |
| macOS Intel | feishu-cli_*_darwin-amd64.tar.gz |
| macOS Apple Silicon | feishu-cli_*_darwin-arm64.tar.gz |
| Windows x64 | feishu-cli_*_windows-amd64.tar.gz |
tar -xzf feishu-cli_*_linux-amd64.tar.gz sudo mv feishu-cli_*/feishu-cli /usr/local/bin/
使用 go install
go install github.com/riba2534/feishu-cli@latest
从源码编译
git clone https://github.com/riba2534/feishu-cli.git cd feishu-cli && make build # 二进制文件输出到 bin/feishu-cli
一键创建应用（推荐）
无需手动访问飞书开放平台后台，一条命令自动完成应用注册：
# 自动创建飞书应用并保存凭证到 ~/.feishu-cli/config.yaml
feishu-cli config create-app --save执行后终端会输出一个授权链接，用飞书扫码确认即可。CLI 自动获取 App ID 和 App Secret 并写入配置文件，后续命令直接可用。
然后在飞书开放平台的应用权限管理页面为新创建的应用开通所需 scope。最快的方式是复制 权限要求 章节的 JSON，在权限管理页面的 导入权限 入口粘贴即可一次性申请全部。
手动配置（不推荐）如果你有特殊需求（如企业应用、自定义应用类型），也可以手动配置：
# 方式一：环境变量 export FEISHU_APP_ID="cli_xxx" export FEISHU_APP_SECRET="xxx" # 方式二：配置文件 feishu-cli config init # 生成模板后手动编辑填入凭证
（可选）如果需要使用搜索、审批任务查询等需要用户身份的功能，还需完成 OAuth 用户授权：
feishu-cli auth login
feishu-cli doc create --title "Hello Feishu"如果返回文档 ID，说明配置成功。
feishu-cli <command> [subcommand] [flags]
Commands:
doc 文档操作（创建、导入、导出、文本级/块级编辑、docs_ai 读取与创建、历史版本、异步导出/导入文件）
wiki 知识库操作（节点增删改查、空间详情、成员管理）
sheet 电子表格（读写、子表名寻址、样式、行列结构/冻结/隐藏、V3 富文本 API、table-get/put、导出 XLSX/CSV、image、filter、dropdown、--as）
bitable 多维表格（base/v3 + bitable/v1：数据表/字段/记录/附件/视图/仪表盘/表单/角色/权限/聚合/工作流，88 命令）
msg 消息操作（发送、转发、合并转发、回复、Pin、表情回复、书签、批量获取、资源下载）
chat 群聊管理（创建、更新、删除、群列表、成员管理）
mail 邮箱操作（分类/搜索、发送、草稿含发送、回复、转发、批量改 label/软删、CID 内联图片、模板、签名）
drive 云盘增强（分块/原地覆盖上传、流式断点续传下载、异步导出/导入、移动、重命名、版本、评论、镜像 pull/push/status、密级标签）
markdown Drive 原生 Markdown 文件 CRUD（.md 整体读写、版本比对，不转换 docx 块）
vc 视频会议（多维搜索、聚合详情、智能纪要 note、会议纪要、录制查询、机器人入会/离会/事件）
minutes 妙记操作（详情 + AI 产物、搜索、权限申请、媒体批量下载）
apps 妙搭（Miaoda）应用（创建、发布 HTML 并等待构建结果、发布记录、修改、访问范围管理）
file 文件管理（列出、移动、复制、删除、上传、下载、版本管理）
media 素材操作（上传、下载）
perm 权限管理（添加、删除、批量添加、公开权限、密码、转移所有权）
calendar 日历操作（日程增删改查、搜索、参与者、忙闲查询、agenda、suggestion、room-find、rsvp）
task 任务操作（增删改查、服务端搜索、子任务、成员、提醒、评论、附件、我的任务）
tasklist 任务清单管理（CRUD、任务关联、成员管理）
attendance 考勤操作（打卡记录查询、统计数据查询）
okr OKR 操作（周期列表/详情、进展记录 CRUD、进展图片上传、--as 身份）
slides Slides 演示文稿（创建带页面、加页/删页/替换、按页读取 XML、截图、媒体上传）
user 用户操作（获取信息、搜索、部门用户列表）
dept 部门操作（详情、子部门列表）
board 画板操作（精排绘图、图表导入、克隆、几何质检 lint、SVG 双向、图片上传、覆盖更新）
comment 评论操作（列出含正文与分页、批量获取、添加、解决/恢复、回复编辑与表情）
approval 审批操作（定义/实例详情、已发起列表、任务查询、实例创建/撤回/抄送、任务通过/拒绝/转交；全部 User Token）
search 搜索操作（消息、应用、文档）
event 实时事件订阅（WebSocket 长连接、list/schema/consume/status/stop）
schema 本地浏览飞书 OpenAPI 方法（无需 token）
api 通用 OpenAPI 透传调用（任意 method/path，自动鉴权 + 错误码翻译，覆盖 2500+ 端点）
profile 多 App / 多账号配置切换
doctor 环境健康检查（config/user_token/endpoints/proxy/deps/catalog/skills 等）
auth 身份认证（OAuth 登录、状态、退出、scope 预检）
config 配置管理
skills 内嵌 AI 技能（list/read/install，与 CLI 版本严格配套）
update 检查并安装最新版本（sha256 校验后原子替换）
通用约定：
--yes 跳过删除类操作的确认；非交互环境（stdin 不是终端）执行这类操作时必须显式带上，否则以退出码 10 退出且不执行。# 创建文档 feishu-cli doc create --title "新文档" # 导入 Markdown（核心功能，默认上传图片） feishu-cli doc import doc.md --title "文档标题" --upload-images --verbose # 导出为 Markdown feishu-cli doc export <doc_id> -o output.md --download-images # 大文档选择性读取（大纲 / 按标题取节 / 关键词定位） feishu-cli doc read <doc_id> --outline feishu-cli doc read <doc_id> --heading "性能优化" feishu-cli doc read <doc_id> --keyword "QPS|限流" --context 5 # 导出他人文档（自动从 auth login 读取 User Token，或手动指定） feishu-cli doc export <doc_id> -o output.md --user-access-token <token> # 获取文档信息 feishu-cli doc get <doc_id> # 获取所有块 feishu-cli doc blocks <doc_id> --all # 添加内容（JSON 格式） feishu-cli doc add <doc_id> -c '<JSON>' # 添加内容（Markdown 格式） feishu-cli doc add <doc_id> README.md --content-type markdown # 原子更新（docs_ai）：纯文本选择器为文本级替换，段落其余内容与样式保留 feishu-cli doc content-update <doc_id> --mode replace_all --selection-with-ellipsis "旧文本" --markdown "新文本" # 按 block id 精确更新（block id 由 doc read --engine docs_ai --with-ids 获得） feishu-cli doc read <doc_id> --engine docs_ai --with-ids --scope keyword --keyword "性能" feishu-cli doc content-update <doc_id> --mode block_replace --block-id <block_id> --markdown "新段落" # 历史版本 feishu-cli doc history list <doc_id> # 带内容建文档：内容里的本地资源在建文档后自动上传绑定（<img href="https://..."> 由服务端下载） feishu-cli doc create --doc-format xml --content-file draft.xml --dry-run # 先预览请求与上传计划 feishu-cli doc create --doc-format xml --content-file draft.xml # draft.xml 可含 <img path="@./a.png"/>、<source path="@./f.pdf"/>、 # <whiteboard type="mermaid" path="@./x.mmd"/>、<html5-block path="@./w.html"/> # 转成可直接发到 IM 的 Markdown feishu-cli doc read <doc_id> --doc-format im-markdown --lang en-US # 文档封面 feishu-cli doc resource update <doc_id> --type cover --file cover.png --offset-ratio-y -0.2 feishu-cli doc resource download <doc_id> --type cover -o ./cover feishu-cli doc resource delete <doc_id> --type cover # 写作草稿：初始化工作区 → 写 DocxXML → 解析预检（字数、块分布、资源） feishu-cli doc script --command init-draft --presentation-decision '{}' feishu-cli doc script --command parse --content @draft_xxxxxxxx_folder/draft.xml # 思维笔记节点（需要应用开通 mindnote:node:read / mindnote:node:create） feishu-cli mindnote nodes list <mindnote_token_or_url> feishu-cli mindnote nodes create <mindnote_token_or_url> --data @nodes.json --dry-run # 添加高亮块 feishu-cli doc add-callout <doc_id> "提示内容" --callout-type info # 批量更新 feishu-cli doc batch-update <doc_id> '[...]' --source-type content # 异步导出为文件（PDF/DOCX/XLSX） feishu-cli doc export-file <doc_token> --type pdf -o output.pdf # 异步导入本地文件为飞书文档 feishu-cli doc import-file local_file.docx --type docx --name "文档名"
feishu-cli wiki spaces # 列出知识空间 feishu-cli wiki get <node_token> # 获取节点 feishu-cli wiki nodes <space_id> # 列出节点 feishu-cli wiki export <node_token> -o doc.md # 导出为 Markdown feishu-cli wiki export-tree <node_token> -o ./backup # 递归导出知识库子树 feishu-cli wiki create --space-id <id> --title "新节点" feishu-cli wiki create --space-id <id> --title "快捷方式" --node-type shortcut --origin-node-token <token> feishu-cli wiki delete <node_token> # 删除节点（官方 API，支持异步任务自动轮询） feishu-cli wiki move-docs <obj_token> --space-id <id> # 移动云空间文档至知识空间 feishu-cli wiki move-to-drive --node-token wikcnXXX --folder-token fldcnYYY # 反向：移出知识库到云盘 feishu-cli wiki space-get <space_id> # 获取知识空间详情 feishu-cli wiki space-create --name "新知识库" # 创建知识库（v1.29+） feishu-cli wiki space-list --page-all -o json # 列出所有可见知识库（v1.29+） feishu-cli wiki node-copy --space-id <src> --node-token <node> --target-space-id <dst> # 复制节点（v1.29+） feishu-cli wiki delete-space <space_id> --yes # 删除整个知识空间（异步任务自动轮询） # 知识空间成员管理 feishu-cli wiki member add <space_id> --member-type userid --member-id USER_ID --role admin feishu-cli wiki member list <space_id> feishu-cli wiki member remove <space_id> --member-type userid --member-id USER_ID --role admin
# V2 API - 基础读写 feishu-cli sheet read <token> "Sheet1!A1:C10" feishu-cli sheet write <token> "Sheet1!A1:B2" --data '[["姓名","年龄"],["张三",25]]' # V3 API - 富文本支持 feishu-cli sheet read-rich <token> <sheet_id> "sheet!A1:C10" # 类型保真整表读写（DataFrame 形状，数字/日期/布尔 dtype 保真，支持 get→改→put round-trip） feishu-cli sheet table-get <token> <sheet_id> [--range A1:D50] feishu-cli sheet table-put <token> <sheet_id> --sheets-file table.json feishu-cli sheet write-rich <token> <sheet_id> --data-file data.json # 行列操作（--start 从 0 开始、--end 不含；或用 --range "3:5"/"B:D"，1 起始两端包含） feishu-cli sheet add-rows <token> <sheet_id> --count 5 feishu-cli sheet add-cols <token> <sheet_id> --count 3 feishu-cli sheet delete-rows <token> <sheet_id> --range "3:5" --dry-run feishu-cli sheet freeze <token> <sheet_id> --rows 1 --cols 1 feishu-cli sheet update-dimension <token> <sheet_id> --range "B:D" --hidden # 身份：默认 User 优先、Tenant 兜底；--as bot 强制以应用身份访问应用自己的表格 feishu-cli sheet list-sheets <token> --as bot # 样式与合并 feishu-cli sheet style <token> "Sheet1!A1:C3" --bold --font-size 14 feishu-cli sheet merge <token> "Sheet1!A1:C1"
# 发送文本消息 feishu-cli msg send --receive-id-type email --receive-id user@example.com --text "Hello" feishu-cli msg send --receive-id-type email --receive-id user@example.com --text "对账" --idempotency-key "bill-001" # 幂等防重发（≤50 字符） # 发送富文本消息 feishu-cli msg send --receive-id-type email --receive-id user@example.com \ --msg-type post --content-file msg.json # 搜索群聊（Bot 身份，仅返回 Bot 所在的群） feishu-cli msg search-chats --query "关键词" # 搜索群聊（User 身份，可搜到用户所在的群） feishu-cli msg search-chats --query "关键词" --user-access-token <token> # 获取群聊历史消息（已 auth login 时自动用 User Token；未登录回落 Bot Token，要求 Bot 在群里） feishu-cli msg history --container-id <chat_id> --container-id-type chat # 获取和某人的私聊记录（邮箱入口，自动搜用户 + 反查 p2p chat_id） feishu-cli msg history --user-email user@example.com --page-size 50 -o json # 已知 open_id 时直接传 feishu-cli msg history --user-id ou_xxx --page-size 50 -o json # 输出 JSON 自动携带顶层 sender_names 映射（open_id → 姓名），AI Agent 可直接引用 # {"items":[...], "sender_names":{"ou_abc":"张三","ou_def":"李四"}} # 转发消息 feishu-cli msg forward <message_id> --receive-id <id> --receive-id-type email # 回复消息 feishu-cli msg reply <message_id> --text "回复内容" feishu-cli msg reply <message_id> --image /path/to/photo.png --idempotency-key "photo-reply-001" # 回复到既有话题：传话题内 om_xxx 消息 ID，不要把 omt_xxx 传给 msg send feishu-cli msg reply om_xxx --file /path/to/report.pdf # 合并转发 feishu-cli msg merge-forward --receive-id user@example.com --receive-id-type email --message-ids id1,id2 # 消息加急 feishu-cli msg urgent <message_id> --user-id-type open_id --user-ids ou_xxx,ou_yyy feishu-cli msg urgent <message_id> --urgent-type phone --user-id-type user_id --user-ids u_123,u_456 feishu-cli msg urgent <message_id> --urgent-type sms --user-id-type union_id --user-ids on_xxx,on_yyy # 表情回复 feishu-cli msg reaction add <message_id> --emoji-type THUMBSUP feishu-cli msg reaction remove <message_id> --reaction-id REACTION_ID feishu-cli msg reaction list <message_id> # Pin 消息 feishu-cli msg pin <message_id> feishu-cli msg unpin <message_id> feishu-cli msg pins --chat-id CHAT_ID
# 添加 / 更新协作者 feishu-cli perm add <doc_id> --doc-type docx --member-type email \ --member-id user@example.com --perm full_access --notification feishu-cli perm update <doc_id> --doc-type docx --member-type email \ --member-id user@example.com --perm edit # 查看 / 删除协作者 feishu-cli perm list <doc_token> --doc-type docx feishu-cli perm delete <doc_token> --doc-type docx --member-type email --member-id user@example.com # 公开权限管理 feishu-cli perm public-get <doc_token> feishu-cli perm public-update <doc_token> --external-access --link-share-entity anyone_readable # 分享密码 feishu-cli perm password create <doc_token> feishu-cli perm password delete <doc_token> # 批量添加协作者 feishu-cli perm batch-add <doc_token> --members-file members.json --notification # 权限检查 feishu-cli perm auth <doc_token> --action view # 转移所有权 feishu-cli perm transfer-owner <doc_token> --member-type email --member-id user@example.com
# 群聊 CRUD feishu-cli chat create --name "群聊名" --user-ids id1,id2 feishu-cli chat get <chat_id> feishu-cli chat update <chat_id> --name "新群名" feishu-cli chat delete <chat_id> feishu-cli chat link <chat_id> # 群成员管理 feishu-cli chat member list <chat_id> feishu-cli chat list --page-all # 列出当前身份加入的全部群 feishu-cli chat member list <chat_id> --page-all # 全量成员（安全截断时告警） feishu-cli chat member add <chat_id> --id-list id1,id2 feishu-cli chat member remove <chat_id> --id-list id1,id2
# 基础操作 feishu-cli file list [folder_token] feishu-cli file mkdir "新文件夹" --parent <folder_token> # 上传 / 下载 feishu-cli file upload local_file.pdf --parent FOLDER_TOKEN feishu-cli file download <file_token> -o output.pdf feishu-cli file download <file_token> -o large.zip --user-access-token u-xxx --timeout 30m # 大文件自动 Range 分片兜底 # 版本管理 feishu-cli file version list <doc_token> --doc-type docx feishu-cli file version revert <file_token> <version> # 回滚到历史版本 feishu-cli file version create <doc_token> --doc-type docx --name "v1.0" feishu-cli file version get <doc_token> <version_id> --doc-type docx feishu-cli file version delete <doc_token> <version_id> --doc-type docx # 元数据与统计 feishu-cli file meta TOKEN1 TOKEN2 --doc-type docx feishu-cli file stats <file_token> --doc-type docx
搜索 API 需要 User Access Token。推荐使用 auth login 一键获取（Token 自动保存和刷新），也可通过 --user-access-token 参数或环境变量手动指定。
# 获取 User Access Token（推荐，一次登录自动刷新） feishu-cli auth login # 搜索消息（默认返回消息 ID，-o json 输出 {MessageIDs,HasMore,PageToken}） feishu-cli search messages "关键词" feishu-cli search messages "会议" --chat-ids oc_xxx,oc_yyy feishu-cli search messages "你好" --chat-type p2p_chat # 搜索私聊消息 feishu-cli search messages "会议" --enrich # 补全内容/发送者/群名/时间 # 搜索应用 feishu-cli search apps "审批" # 搜索文档和 Wiki feishu-cli search docs "产品需求" feishu-cli search docs "季度报告" --docs-types doc,sheet feishu-cli search docs "技术方案" --count 10 feishu-cli search docs "技术方案" --count 10 --page-token <上一页输出的 page_token> # 翻页（--offset 已不支持） # 也可以手动指定 Token feishu-cli search docs "产品需求" --user-access-token <token> export FEISHU_USER_ACCESS_TOKEN="u-xxx" feishu-cli search docs "产品需求"
全部当前审批 API 使用 User Token。approval get 走 GET /open-apis/approval/v4/approvals/{approval_code}/detail，需要 approval:approval:read；approval instance get 走 GET .../instances/detail，需要 approval:instance:read；approval instance initiated 走 GET .../instances/initiated；approval task query 走 GET .../tasks（不传 user_id query），需要 approval:task:read。写流程：instance create → POST .../instances/initiate（approval:instance:write，发起人取当前登录用户）；instance cancel → POST .../instances/recall；instance cc → POST .../instances/add_cc；task approve/reject/transfer → POST .../tasks/pass|refuse|forward。
输出说明：
--output：输出便于阅读的文本摘要--output json：输出 CLI 归一化后的 JSON，部分字段会做拍平和字符串化处理--output raw-json：输出飞书 API 原始成功响应；HTTP 200 但业务 code != 0 时非零退出# 查询审批定义详情（User Token） feishu-cli approval get <approval_code> # 输出完整 JSON feishu-cli approval get <approval_code> --output json # 输出飞书 API 原始响应 feishu-cli approval get <approval_code> --output raw-json # 查询审批实例详情（User Token） feishu-cli approval instance get --instance-code <instance_code> feishu-cli approval instances get --instance-code <instance_code> --output raw-json # 查询我发起的审批实例 feishu-cli approval instance initiated feishu-cli approval instance initiated --output json # 查询当前登录用户的待我审批 feishu-cli approval task query --topic todo # 查询我已审批的任务 feishu-cli approval task query --topic done # 查询抄送给我的（未读 / 已读） feishu-cli approval task query --topic cc-unread --output json feishu-cli approval task query --topic cc-read # 输出飞书 API 原始响应 feishu-cli approval task query --topic todo --output raw-json # 注：--topic 仅接受 todo / done / cc-unread / cc-read（服务端 options 为 1/2/17/18）。 # started（topic=3）已被官方下线，查「我发起的」请用上面的 approval instance initiated # 翻页查询 feishu-cli approval task query --topic todo --page-size 20 --page-token <token> # 显式指定 User Access Token feishu-cli approval task query --topic cc-unread --user-access-token <token> # 发起审批实例（身份取当前 User Token；form.json 为飞书审批表单 JSON 数组） feishu-cli approval instance create --approval-code <code> --form-file form.json # 撤回 / 抄送审批实例 feishu-cli approval instance cancel --instance-code <instance_code> feishu-cli approval instance cc --instance-code <instance_code> --cc-user-ids ou_a,ou_b # 通过 / 拒绝审批任务 feishu-cli approval task approve --instance-code <instance_code> --task-id <task_id> --comment "同意" feishu-cli approval task reject --instance-code <instance_code> --task-id <task_id> --comment "信息不完整" # 转交审批任务（User Token） feishu-cli approval task transfer --instance-code <instance_code> --task-id <task_id> --transfer-user-id ou_target --comment "请代审"
通过 OAuth 2.0 Device Flow（RFC 8628） 获取 User Access Token，用于搜索、审批待办查询等需要用户授权的功能。无需在飞书开放平台配置任何重定向 URL 白名单。
v1.18+ 变更：Authorization Code Flow（
--print-url/auth callback/--manual/--port/--method/--scopes）已全部删除，只保留 Device Flow。
# 按业务域申请推荐权限（推荐） feishu-cli auth login --domain search --recommend # 显式申请某组 scope feishu-cli auth login --scope "minutes:minutes.basic:read minutes:minutes.transcript:export" # JSON 事件流输出（AI Agent 推荐，配合 run_in_background 使用） feishu-cli auth login --domain search --recommend --json # 两步模式：先立即输出 device_code，不启动轮询 feishu-cli auth login --domain vc --domain minutes --recommend --no-wait --json # 两步模式：用已有 device_code 继续轮询 feishu-cli auth login --device-code <device_code> --json # 预检 token 是否包含所需 scope（AI Agent 推荐在执行业务命令前调用） feishu-cli auth check --scope "search:docs:read" feishu-cli auth check --scope "search:docs:read im:message:readonly" # 查看当前授权状态 feishu-cli auth status feishu-cli auth status -o json # JSON 格式输出 # 退出登录（清除本地 token） feishu-cli auth logout
登录时 CLI 在 stderr 打印验证链接和 user_code，用户在任意设备（电脑、手机）浏览器打开链接完成授权即可。本地桌面会尝试自动打开浏览器，SSH 远程失败静默忽略。
授权范围策略：
auth check --scope "REQ_SCOPES" 预检，再用 auth login --scope "..." 或 auth login --domain ... --recommend 补授权auth:user.id:read）用于识别当前登录用户Token 管理：
~/.feishu-cli/token.json（0600，原子写入），Access Token 有效期约 2 小时token.json 带 app_id 绑定；与当前 App 不一致或旧文件未绑定时，一律拒绝使用（即使 access 仍有效）。迁移：feishu-cli auth token --bind-legacy-app --as user（不更换 token；不可与 --as bot / --user-access-token 同时用）或重新 auth loginauth token --as bot 走官方 Accounts OAuth v3 client_credentials；不可与 --user-access-token 同时使用offline_access 由 CLI 自动追加，无需手动声明--user-access-token 参数 > FEISHU_USER_ACCESS_TOKEN 环境变量 > token.json > config.yaml~/.feishu-cli/user_profile.json，登录态变化或执行 auth logout 时会自动清理base_url 默认仅官方 HTTPS。自定义远端 / 明文 HTTP / 带 body 跨源重定向需显式 opt-in（FEISHU_ALLOW_CUSTOM_BASE_URL、FEISHU_ALLOW_INSECURE_HTTP、FEISHU_ALLOW_CROSS_ORIGIN_REDIRECT）# 文档异步导出/导入 feishu-cli doc export-file <doc_token> --type pdf -o output.pdf feishu-cli doc import-file local_file.docx --type docx --name "文档名" # 素材上传 feishu-cli media upload image.png --parent-type docx_image --parent-node <doc_id> # 日历 feishu-cli calendar list feishu-cli calendar get <calendar_id> feishu-cli calendar primary feishu-cli calendar create-event --calendar-id <id> --summary "会议" \ --start "2024-01-01T10:00:00+08:00" --end "2024-01-01T11:00:00+08:00" feishu-cli calendar event-search --calendar-id <id> --query "关键词" feishu-cli calendar event-reply <calendar_id> <event_id> --status accept feishu-cli calendar attendee add <calendar_id> <event_id> --user-ids id1,id2 feishu-cli calendar attendee list <calendar_id> <event_id> feishu-cli calendar freebusy --start "2024-01-01T00:00:00+08:00" \ --end "2024-01-02T00:00:00+08:00" --user-ids id1,id2 # 任务 feishu-cli task create --summary "待办事项" feishu-cli task complete <task_id> feishu-cli task subtask create <task_guid> --summary "子任务" feishu-cli task subtask list <task_guid> feishu-cli task member add <task_guid> --members id1,id2 --role assignee feishu-cli task reminder add <task_guid> --minutes 30 feishu-cli task upload-attachment --task-guid <task_guid> --file ./report.pdf # 任务列表 feishu-cli tasklist create --name "任务列表" feishu-cli tasklist list feishu-cli tasklist get <tasklist_guid> feishu-cli tasklist delete <tasklist_guid> # 画板（v1.25+ 新增 5 个子命令 + Mermaid 本地引擎 + Markdown ```svg fence 自动识别） feishu-cli board create-notes <whiteboard_id> nodes.json -o json # 精排绘图（JSON 控制坐标、颜色、连线） feishu-cli board import <whiteboard_id> "graph TD; A-->B" --source-type content --syntax mermaid --diagram-type flowchart # 服务端渲染 feishu-cli board import <whiteboard_id> diagram.mmd --syntax mermaid --engine local # 本地引擎（whiteboard-cli 翻译，每个节点可单独编辑） feishu-cli board import <whiteboard_id> diagram.puml --syntax plantuml # 导入 PlantUML feishu-cli board svg-import <whiteboard_id> drawing.svg # 单 svg 节点装饰（图标/印章 < 2KB） feishu-cli board svg-export <whiteboard_id> -o board.svg # 服务端 SVG 导出 feishu-cli board clone <source_id> <target_id> --batch-size 10 # 克隆画板（含 connector ID 重映射 + 分批节流） feishu-cli board upload-image <whiteboard_id> photo.png # 上传本地图片为 image 节点（自动推断像素尺寸） feishu-cli board lint <whiteboard_id> # 几何质检（重叠/字号一致性/容量/综合评分） feishu-cli board export-code <whiteboard_id> --merge --output-path design.svg # 反向导出 SVG（按 z_index 排序） feishu-cli board update <whiteboard_id> nodes.json --overwrite --snapshot old.json # 覆盖更新+快照备份 feishu-cli board nodes <whiteboard_id> # 获取画板所有节点 feishu-cli board image <whiteboard_id> output # 下载画板截图（自动按实际格式补扩展名，通常 JPEG） # ⭐ AI 自由作图（飞轮/鱼骨/Dashboard/插画/周期表/赛博朋克等）：用 skill 的一键脚本，每个矢量元素都可单独点击编辑 python3 skills/feishu-cli-visual/references/workflows/board/scripts/svg_to_board.py drawing.svg <whiteboard_id> # 内置 5 步管道：whiteboard-cli 翻译 → 修 z_index → 修剪 viewBox 溢出 → 分批 create-notes → 验证 # 评论 feishu-cli comment list <file_token> --type docx feishu-cli comment add <file_token> --type docx --text "评论内容" feishu-cli comment resolve <file_token> <comment_id> --type docx feishu-cli comment unresolve <file_token> <comment_id> --type docx feishu-cli comment reply list <file_token> <comment_id> --type docx feishu-cli comment reply delete <file_token> <comment_id> <reply_id> --type docx # 多维表格（base/v3 API） feishu-cli bitable create --name "项目管理" --time-zone Asia/Shanghai feishu-cli bitable table list --base-token bscnxxxx feishu-cli bitable table create --base-token bscnxxxx --name "任务" feishu-cli bitable field list --base-token bscnxxxx --table-id tblxxx feishu-cli bitable field create --base-token bscnxxxx --table-id tblxxx --config '{"name":"状态","type":"select"}' feishu-cli bitable record upsert --base-token bscnxxxx --table-id tblxxx --config '{"fields":{"名称":"测试"}}' feishu-cli bitable record upsert --base-token bscnxxxx --table-id tblxxx --record-id recxxx --config '{"fields":{"状态":"完成"}}' feishu-cli bitable record batch-create --base-token bscn
| ||
| | |
| ||
| ||
| ||
| ||
| ||
| ||
|
| |
| |
| |
| |
| |
| |
| |
| |
|
| |||
| |||
| |||
| |||
| |||
| |||
| |||
| |||
| |||
| |||
| |||
| |||
| |||
| |||
|