feishu-cli

feishu-cli 是一个功能完善的飞书开放平台命令行工具。它将飞书文档、知识库、电子表格、消息、日历、任务等操作封装为简洁的命令行接口，核心能力是 Markdown ↔ 飞书文档的双向无损转换。

feishu-cli

飞书开放平台命令行工具 — Markdown 与飞书文档双向转换，AI Agent 的飞书操控引擎

介绍 · 30 秒上手 · 核心能力 · 快速开始 · 命令参考 · AI 技能 · FAQ · 更新日志

feishu-cli 是什么

feishu-cli 是一个功能完整的飞书开放平台命令行工具。它将飞书文档、知识库、电子表格、消息、日历、任务等操作封装为简洁的命令行接口，核心能力是 Markdown ↔ 飞书文档双向无损转换。

除了传统的 CLI 用法，feishu-cli 还为 Claude Code 等 AI 编程助手提供了 9 个开箱即用的领域技能（Skill），让 AI Agent 能够直接创建文档、发送消息、管理权限——无需任何额外配置。

注意：feishu-cli 主要面向 AI Agent（如 Claude Code）使用，通过技能文件让 AI 直接操控飞书。虽然人类也可以直接使用命令行，但大多数场景下建议通过 AI Agent 调用，体验更佳。

为什么选择 feishu-cli

双向转换零损耗 — 支持 40+ 种块类型，Markdown 导入飞书后再导出，内容完整保留
图表原生渲染 — Mermaid（8 种图表类型）和 PlantUML 自动转换为飞书画板，不是截图，是可编辑的矢量图
大规模文档处理 — 三阶段并发管道架构，实测 10,000+ 行 / 127 个图表 / 170+ 个表格一次导入
P2P 私聊原生可读 — msg history --user-email 一条命令打通「搜用户 → 反查 p2p chat_id → 读消息」，输出自动带 sender_names 映射，AI Agent 直接拿结构化带名消息流，无需额外查群成员
AI Agent 原生 — 9 个领域技能覆盖飞书全功能（503 个命令全部归属），AI 助手即装即用
为脚本与 Agent 设计的健壮性 — 错拼命令/flag 报错并给拼写建议（绝不静默成功）、写操作 --dry-run、幂等键防重发、统一 --jq/--format 结构化输出
一个工具覆盖全平台 — 文档、知识库、表格、多维表格、消息、邮箱、日历、任务、考勤、OKR、视频会议、妙记、云盘、权限、画板、Slides、事件、Schema、Profile、健康检查

三十秒上手

# 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。支持完整语法转换：

# 导入：Markdown → 飞书文档
feishu-cli doc import report.md --title "技术报告" --verbose

# 导出：飞书文档 → Markdown
feishu-cli doc export  -o doc.md --download-images

支持的语法：标题（6 级）、段落、列表（无限深度嵌套）、任务列表、代码块、引用、Callout（6 种类型）、同步块（含跨文档引用）、表格（自动拆分）、分割线、图片、链接、公式、粗体 / 斜体 / 删除线 / 下划线 / 行内代码 / 高亮。跨文档同步块无法读取时会保留带源标识的 WARNING 占位并输出诊断，不会静默导出为空。

Mermaid / PlantUML 图表

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%，失败图表自动降级为代码块并保留原文，不阻断整篇导入。

智能表格处理

列宽自动计算 — 根据内容智能调整，中英文字符区分宽度（中文 14px，英文 8px）
列宽自定义（v1.29+，issue #156）— 支持紧邻表格上方注释 ``（单位 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，视觉上为一张连贯的表，不再拆成多张独立表格
批量填充加速（v1.29+，issue #159）— 单元格填充改用 batch_update API（每批 ≤30）+ 文档级 3 QPS 节流，典型 4×6×8 表场景从 ~70s 降到 ~3s
单元格多块内容 — 支持 bullet / heading / text 混合内容

三阶段并发管道

导入大文档时，feishu-cli 使用三阶段并发管道最大化吞吐量：

阶段一（顺序） — 按文档顺序创建所有块，收集图表和表格任务
阶段二（并发） — 图表 worker 池 + 表格 worker 池并发处理
阶段三（逆序） — 处理失败图表，降级为代码块

feishu-cli doc import large-doc.md --title "大文档" \
  --upload-images --diagram-workers 5 --table-workers 3 --image-workers 2 --verbose

全功能 API 覆盖

展开 20+ 模块能力总览表

模块	能力
文档	创建、导入、导出、大文档选择性读取（doc read：大纲/按标题取节/关键词定位）、编辑、批量更新、Callout、画板、异步导出/导入文件
知识库	空间列表、节点增删改查、导出（含整树递归镜像）、移出知识库到云盘（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` 裸调任意未封装的 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，在权限管理页面的 导入权限 入口粘贴即可一次性申请全部。

手动配置（不推荐）

如果你有特殊需求（如企业应用、自定义应用类型），也可以手动配置：

在飞书开放平台创建应用，获取 App ID 和 App Secret
给应用添加所需权限（参见权限要求）
配置凭证（二选一）：

# 方式一：环境变量
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，说明配置成功。

命令参考

…

文档操作

…

知识库操作

…

电子表格操作

…

消息操作

…

权限管理

…

群聊管理

# 群聊 CRUD
feishu-cli chat create --name "群聊名" --user-ids id1,id2
feishu-cli chat get 
feishu-cli chat update  --name "新群名"
feishu-cli chat delete 
feishu-cli chat link 

# 群成员管理
feishu-cli chat member list 
feishu-cli chat list --page-all                                    # 列出当前身份加入的全部群
feishu-cli chat member list  --page-all                   # 全量成员（安全截断时告警）
feishu-cli chat member add  --id-list id1,id2
feishu-cli chat member remove  --id-list id1,id2

文件管理

…

搜索操作

搜索 API 需要 User Access Token。推荐使用 auth login 一键获取（Token 自动保存和刷新），也可通过 --user-access-token 参数或环境变量手动指定。

…

审批操作

全部当前审批 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 时非零退出

…

身份认证（Device Flow）

通过 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。

…

登录时 CLI 在 stderr 打印验证链接和 user_code，用户在任意设备（电脑、手机）浏览器打开链接完成授权即可。本地桌面会尝试自动打开浏览器，SSH 远程失败静默忽略。

授权范围策略：

CLI 会显式声明本次请求的 scope，不再依赖“后台开了什么就全量返回”
推荐先用 auth check --scope "REQ_SCOPES" 预检，再用 auth login --scope "..." 或 auth login --domain ... --recommend 补授权
即使显式请求业务 scope，CLI 也会自动追加最小核心 scope（如 auth:user.id:read）用于识别当前登录用户
要真正拿到某个 scope，仍然必须先在飞书开放平台应用权限管理页面开通它

Token 管理：

Token 保存在 ~/.feishu-cli/token.json（0600，原子写入），Access Token 有效期约 2 小时
Access Token 过期时自动使用 Refresh Token 刷新（跨进程锁，避免两个进程消耗同一 refresh token）
新登录写入的 token.json 带 app_id 绑定；与当前 App 不一致或旧文件未绑定时，一律拒绝使用（即使 access 仍有效）。迁移：feishu-cli auth token --bind-legacy-app --as user（不更换 token；不可与 --as bot / --user-access-token 同时用）或重新 auth login
auth token --as bot 走官方 Accounts OAuth v3 client_credentials；不可与 --user-access-token 同时使用
offline_access 由 CLI 自动追加，无需手动声明
Token 优先级：--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）

更多命令

…

svg fence 自动识别） feishu-cli board create-notes nodes.json -o json # 精排绘图（JSON 控制坐标、颜色、连线） feishu-cli board import "graph TD; A-->B" --source-type content --syntax mermaid --diagram-type flowchart # 服务端渲染 feishu-cli board import diagram.mmd --syntax mermaid --engine local # 本地引擎（whiteboard-cli 翻译，每个节点可单独编辑） feishu-cli board import diagram.puml --syntax plantuml # 导入 PlantUML feishu-cli board svg-impor

feishu-cli

工具介绍

feishu-cli 是什么

为什么选择 feishu-cli

三十秒上手

核心能力

Markdown ↔ 飞书文档

Mermaid / PlantUML 图表

智能表格处理

三阶段并发管道

全功能 API 覆盖

快速开始

安装

配置凭证

验证安装

命令参考

Issues· 0 开放

> 标签

> 工具信息

> 相关工具

feishu-cli

工具介绍

feishu-cli 是什么

为什么选择 feishu-cli

三十秒上手

核心能力

Markdown ↔ 飞书文档

Mermaid / PlantUML 图表

智能表格处理

三阶段并发管道

全功能 API 覆盖

快速开始

安装

配置凭证

验证安装

命令参考

Issues· 0 开放

> 标签

> 讨论区

> 工具信息

> 相关工具