feishu_cli封面图

Feishu CLI – 飞书开放平台命令行工具

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

介绍
核心能力
快速开始
命令参考
AI 技能集成
贡献

Feishu CLI 是什么

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

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

核心能力

双向转换零损耗

支持 40+ 种块类型，Markdown 导入飞书后再导出，内容完整保留。

图表原生渲染

Mermaid（8 种图表类型） 和 PlantUML 自动转换为飞书画板，不是截图，是可编辑的矢量图。

大规模文档处理

三阶段并发管道架构，实测 10,000+ 行 / 127 个图表 / 170+ 个表格 一次导入。

AI Agent 原生

11 个技能文件覆盖飞书全功能，AI 助手即装即用。

一个工具覆盖全平台

文档、知识库、表格、消息、日历、任务、权限、画板、评论、搜索。

快速开始

安装

一键安装（推荐）
自动检测平台，下载最新版本并安装到 /usr/local/bin：

curl -fsSL https://raw.githubusercontent.com/riba2534/feishu-cli/main/install.sh | bash

已安装的用户执行同样的命令即可更新到最新版本。

其他安装方式

手动下载：从 Releases 页面下载对应平台的压缩包。

使用 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

配置

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

# 方式一：环境变量（推荐）
export FEISHU_APP_ID="cli_xxx"
export FEISHU_APP_SECRET="xxx"

# 方式二：配置文件 ~/.feishu-cli/config.yaml
feishu-cli config init

（可选）如果需要使用搜索、审批任务查询等需要用户身份的功能，还需完成 OAuth 用户授权：

# 前置条件：在飞书开放平台 → 应用详情 → 安全设置 → 重定向 URL 中添加：
# http://127.0.0.1:9768/callback

# 一键 OAuth 登录
feishu-cli auth login

验证

feishu-cli doc create --title "Hello Feishu"

如果返回文档 ID，说明配置成功。

命令参考

feishu-cli <command> [subcommand] [flags]

文档操作

# 创建文档
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
# 导出他人文档（自动从 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

# 添加高亮块
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>  # 列出节点

# 导出为 Markdown
feishu-cli wiki export <node_token> -o doc.md

# 创建节点
feishu-cli wiki create --space-id <id> --title "新节点"

# 获取知识空间详情
feishu-cli wiki space-get <space_id>

# 知识空间成员管理
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"
feishu-cli sheet write-rich <token> <sheet_id> --data-file data.json

# 行列操作
feishu-cli sheet add-rows <token> <sheet_id> --count 5
feishu-cli sheet add-cols <token> <sheet_id> --count 3

# 样式与合并
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 
  --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>

# 获取历史消息（Bot 不在群内时使用 --user-access-token）
feishu-cli msg history --container-id <chat_id> --container-id-type chat

# 转发消息
feishu-cli msg forward <message_id> --receive-id <id> --receive-id-type email

# 回复消息
feishu-cli msg reply <message_id> --text "回复内容"

# 合并转发
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 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 --name "新文件夹" --folder-token <token>

# 上传 / 下载
feishu-cli file upload local_file.pdf --parent FOLDER_TOKEN
feishu-cli file download <file_token> -o output.pdf

# 版本管理
feishu-cli file version list <doc_token> --doc-type docx
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

# 搜索消息
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 apps "审批"

# 搜索文档和 Wiki
feishu-cli search docs "产品需求"
feishu-cli search docs "季度报告" --docs-types doc,sheet
feishu-cli search docs "技术方案" --count 10 --offset 0

# 也可以手动指定 Token
feishu-cli search docs "产品需求" --user-access-token <token>
export FEISHU_USER_ACCESS_TOKEN="u-xxx"
feishu-cli search docs "产品需求"

审批操作

approval get 使用应用权限查询审批定义（审批模板/流程定义），支持 --output raw-json 查看飞书 API 原始响应，需要开通 approval:approval:readonly；approval task query 会优先根据当前 auth login 登录态自动识别当前用户，需要开通 approval:task 并完成用户授权。

# 查询审批定义详情（审批模板/流程定义）
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

# 查询当前登录用户的待我审批
feishu-cli approval task query --topic todo

# 查询我已审批的任务
feishu-cli approval task query --topic done

# 查询我发起的审批
feishu-cli approval task query --topic started --output json

# 输出飞书 API 原始响应
feishu-cli approval task query --topic started --output raw-json

# 翻页查询
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>

身份认证

通过 OAuth 2.0 获取 User Access Token，用于搜索、审批待办查询等需要用户授权的功能。

前置条件：在飞书开放平台 → 应用详情 → 安全设置 → 重定向 URL 中添加 http://127.0.0.1:9768/callback

# 登录授权（自动打开浏览器完成 OAuth）
feishu-cli auth login

# SSH 远程环境使用手动模式
feishu-cli auth login --manual

# 指定端口（默认 9768）
feishu-cli auth login --port 8080

# 指定 OAuth scope（建议加 offline_access 以获取 Refresh Token）
feishu-cli auth login --scopes "search:docs:read search:message offline_access"

# 非交互模式（AI Agent 推荐，不阻塞 stdin）
feishu-cli auth login --print-url  # 步骤 1：输出授权 URL 和 state
feishu-cli auth callback "<回调URL>" --state "<state>"  # 步骤 2：用回调 URL 换 token

# 查看当前授权状态
feishu-cli auth status
feishu-cli auth status -o json  # JSON 格式输出

# 退出登录（清除本地 token）
feishu-cli auth logout

Token 管理：

Token 保存在 ~/.feishu-cli/token.json，Access Token 有效期约 2 小时
Access Token 过期时自动使用 Refresh Token 刷新（Refresh Token 有效期 30 天）
重要：登录时需包含 offline_access scope 才会返回 Refresh Token，否则 2 小时后需重新登录
Token 优先级：--user-access-token 参数 > FEISHU_USER_ACCESS_TOKEN 环境变量 > token.json > config.yaml
审批任务查询会缓存当前登录用户资料到 ~/.feishu-cli/user_profile.json，登录态变化或执行 auth logout 时会自动清理

AI 技能集成

skills/ 目录包含 11 个为 Claude Code 设计的技能文件，让 AI Agent 能够直接操作飞书 — 创建文档、发送消息、管理权限，全部通过自然语言驱动。

技能	功能	触发示例
feishu-cli-read	读取飞书文档 / 知识库	"读一下这个飞书链接"
feishu-cli-write	创建 / 写入 / 更新文档	"创建一个新飞书文档"
feishu-cli-import	从 Markdown 导入创建文档	"把这个 md 文件上传到飞书"
feishu-cli-export	导出为 Markdown / PDF / Word	"把飞书文档导出来"
feishu-cli-perm	权限管理	"给文档添加权限"
feishu-cli-msg	消息全功能管理	"发消息给 xxx"
feishu-cli-toolkit	综合工具箱（表格/日历/任务/群聊/文件/评论/知识库/通讯录）	"读取飞书表格数据"
feishu-cli-board	画板操作（精排绘图/Mermaid 导入/截图/节点管理）	"画个架构图"、"在飞书里画图"
feishu-cli-auth	OAuth 认证、Token 管理、scope 配置	"登录飞书"、"获取 Token"
feishu-cli-search	搜索飞书文档 / 消息 / 应用	"搜索飞书文档"
feishu-cli-doc-guide	飞书文档创建规范	其他技能内部引用

安装方法：

# 一键安装全部技能（推荐）
npx skills add riba2534/feishu-cli --global --yes --agent claude-code --copy

# 或手动复制
# 将 skills/ 目录复制到 ~/.claude/skills/

权限要求

在飞书开放平台为你的应用添加以下权限：

功能	所需权限	说明
文档操作	`docx:document`	文档读写
知识库	`wiki:wiki:readonly`	知识库读取
知识库成员	`wiki:member`	空间成员管理
云空间文件	`drive:drive, drive:drive:readonly`	文件管理
评论	`docs:document.comment`	评论读写
权限管理	`docs:permission.member:create`	添加协作者
消息	`im:message, im:message:send_as_bot`	发送消息
消息增强	`im:message.pins, im:message.reactions`	Pin/Reaction/转发
消息加急	`im:message.urgent, im:message.urgent:phone, im:message.urgent:sms, im:message.urgent.status:write`	消息加急（应用内/电话/短信）
群聊管理	`im:chat`	群聊 CRUD
群成员管理	`im:chat.members`	群成员操作
会话历史	`im:message:readonly`	获取历史消息
群消息读取（User 身份）	`im:message.group_msg:get_as_user`	User Token 读取群消息
画板	`board:whiteboard`	画板读写
电子表格	`sheets:spreadsheet`	电子表格读写
素材管理	`subscriptions:image`	上传下载, 需单独申请
用户信息	`contact:user.base:readonly`	获取用户信息, 需单独申请
通讯录	`contact:contact.base:readonly`	需单独申请
部分搜索	`directory:department:search`	需单独申请
日历	`calendar:calendar`	需单独申请
任务	`task:task:read, task:task:write`	需单独申请
任务列表	`task:tasklist:read, task:tasklist:write`	任务列表管理
审批定义查询	`approval:approval:readonly`	用于 approval get
审批任务查询	`approval:task`	用于 approval task query，并需完成用户授权
搜索消息/应用	需要 User Access Token	通过 auth login 或手动获取
搜索文档	需要 User Access Token	通过 auth login 或手动获取，支持 search:read 权限
读取他人文档（User 身份）	`docx:document:readonly`（User scope）	通过 `feishu-cli auth login --scopes "docx:document:readonly offline_access"` 授权
搜索云文档（User 身份）	`search:docs:read`（User scope）	通过 `feishu-cli auth login --scopes "search:docs:read offline_access"` 授权
离线刷新 Token	`offline_access`（User scope）	与其他 scope 一起传入，获取 Refresh Token 以自动续期

技术栈

组件	选型	说明
语言	Go 1.21+
CLI 框架	cobra	子命令、自动补全
飞书 SDK	oapi-sdk-go/v3	官方 SDK
配置管理	viper	YAML / 环境变量
Markdown	goldmark	GFM 扩展支持

项目结构

feishu-cli/
├── cmd/                      # CLI 命令（每个子命令一个文件）
│   ├── root.go              # 根命令、全局配置
│   ├── import_markdown.go   # Markdown 导入（三阶段并发管道）
│   ├── export_markdown.go   # 导出为 Markdown
│   └── ...
├── internal/
│   ├── client/              # 飞书 API 封装
│   ├── converter/           # Markdown ↔ Block 转换器
│   └── config/              # 配置管理
├── skills/                   # Claude Code AI 技能文件
├── main.go
├── Makefile
└── install.sh               # 一键安装脚本

贡献

# 克隆项目
git clone https://github.com/riba2534/feishu-cli.git
cd feishu-cli

# 安装依赖
go mod tidy

# 构建
make build          # 输出到 bin/feishu-cli
make build-all      # 多平台构建

# 测试
go test ./...

# 代码检查
go vet ./...

欢迎提交 Issue 和 Pull Request！