飞书 CLI 使用指南：打通飞书与本地笔记的双向流动
飞书文档和本地笔记能否打通？数据散落在飞书、Obsidian 各平台，每个都是孤岛。飞书官方 CLI 工具
lark-cli（又名 feishu-cli）提供了 200+ 命令覆盖 18 个业务领域，让你的内容在两个世界自由流动。
先说结论：为什么一定要打通？
知识工作者的普遍痛点：
- 飞书写了一半的文章想归档到本地 Obsidian
- Obsidian 写好的笔记想发到飞书协作
- 飞书多维表格里的选题库想同步到本地管理
- 每查一次资料要在 3-4 个平台间切换
打破数据孤岛，只需要一个 CLI 工具。官方团队开源了 lark-cli（又名 feishu-cli），定位是"for humans and AI Agents"——既适合人类终端操作，也适合 AI Agent 调用。
第一章：飞书 CLI 到底是什么
lark-cli 是飞书（Lark）官方团队开源的多功能命令行工具，Go 语言编写，使用 MIT 许可证。GitHub 地址：https://github.com/larksuite/cli
核心能力：
| 能力 | 说明 |
|---|---|
| 200+ 命令 | 覆盖 18 个业务领域 |
| 三层命令系统 | 快捷命令、API 命令、原始 API 调用 |
| 26 个 Agent Skills | 专为 AI Agent 设计的技能模块 |
| 多身份切换 | 支持用户身份和机器人身份切换 |
| 多种输出格式 | json / pretty / table / ndjson / csv |
覆盖的业务领域：
日历、即时通讯、文档、云盘、多维表格、电子表格、幻灯片、任务、知识库、通讯录、邮件、会议、考勤、审批、OKR、白板、项目、应用管理。
注：项目相关的功能由单独的 meegle-cli 提供。
第二章：安装和授权
安装
推荐方式（npm）：
1npx @larksuite/cli@latest install
这会在全局安装 lark-cli 命令行工具。装完后验证：
1lark-cli --version
从源码编译：
1git clone https://github.com/larksuite/cli.git
2cd cli
3make install
4npx skills add larksuite/cli -y -g
前提条件：Go ≥ 1.23、Node.js/npm、Python 3（仅源码编译需要）。
授权
首次使用需要配置和登录：
1# 初始化配置（交互式）
2lark-cli config init
3
4# OAuth 登录（推荐）
5lark-cli auth login --recommend
6
7# 查看登录状态
8lark-cli auth status
登录流程会打开浏览器，完成飞书 OAuth 授权。登录后凭据存储在系统密钥链中（OS-native keychain），安全可靠。
多账号管理：
1# 查看所有已认证用户
2lark-cli auth list
3
4# 切换身份
5lark-cli auth login --as bot # 机器人身份
6lark-cli auth login --as user # 用户身份
7
8# 检查某个权限范围
9lark-cli auth check calendar:read
10
11# 列出所有可用权限范围
12lark-cli auth scopes
第三章：核心操作（三层命令系统）
lark-cli 设计了三个层次的命令，从便捷到灵活逐步递进。
第一层：快捷命令（Shortcuts）
前缀为 +，专为人类和 AI 设计，内置智能默认值，支持 --dry-run 预览。
1# 查看日历议程
2lark-cli calendar +agenda
3
4# 发送消息
5lark-cli im +send --to user --text "Hello"
6
7# 创建文档
8lark-cli doc +create --title "周报" --content "# 周报内容"
第二层：API 命令
由飞书 OpenAPI 元数据自动生成，100+ 命令与平台端点 1:1 映射。
1# 列出日历
2lark-cli calendar calendars list
3
4# 获取文档内容
5lark-cli doc documents get --document_id xxx
6
7# 搜索文档
8lark-cli doc search --query "关键词"
第三层：原始 API 调用
覆盖 2500+ API，调用任意飞书开放平台端点。
1# 调用任意 API
2lark-cli api GET /open-apis/calendar/v4/calendars
3
4# POST 请求带参数
5lark-cli api POST /open-apis/im/v1/messages \
6 --body '{"receive_id":"user_id","msg_type":"text","content":"hello"}'
通用参数
1# 指定输出格式
2--format json | pretty | table | ndjson | csv
3
4# 分页控制
5--page-all # 获取所有页
6--page-limit 50 # 每页 50 条
7--page-delay 200 # 页间隔 200ms
8
9# 预览模式（不实际执行）
10--dry-run
第四章：文档操作工作流
4.1 从飞书读取文档到本地
1# 获取文档内容（Markdown 格式）
2lark-cli doc documents get --document_id xxx --format markdown > doc.md
3
4# 搜索文档
5lark-cli doc search --query "项目方案" --limit 10
4.2 把本地文档上传到飞书
1# 创建新文档
2lark-cli doc create --title "文章标题" --content "$(cat article.md)"
3
4# 上传到指定文件夹
5lark-cli doc create --title "文章标题" --content "$(cat article.md)" \
6 --folder_id xxx
4.3 更新飞书文档
1lark-cli doc update --document_id xxx --title "新标题" --content "新内容"
注意：更新操作需要指定
--document_id，且更新后的内容会完全替换原有内容，不是增量追加。
4.4 搜索飞书文档
1# 全文搜索
2lark-cli doc search --query "关键词"
3
4# 按分类搜索
5lark-cli doc search --query "周报" --scope wiki
4.5 操作飞书多维表格
1# 列出所有表格
2lark-cli base tables list
3
4# 读取表格记录
5lark-cli base records list --table_id xxx --app_token yyy
6
7# 新增记录
8lark-cli base records append --table_id xxx --app_token yyy \
9 --fields '{"标题":"测试","状态":"进行中"}'
10
11# 导出表格
12lark-cli sheets export --spreadsheet_token xxx --format csv
4.6 操作飞书知识库
1# 列出知识库
2lark-cli wiki list
3
4# 获取知识库节点内容
5lark-cli wiki node get --node_id xxx
6
7# 搜索知识库
8lark-cli wiki search --query "关键词"
第五章：和 Obsidian 配合的工作流
场景一：飞书文档 → Obsidian 归档
1# 1. 搜索文档
2lark-cli doc search --query "需要归档" --format json
3
4# 2. 获取文档内容并保存为 Markdown
5lark-cli doc documents get --document_id xxx --format markdown \
6 > "obsidian-vault/归档/文档标题.md"
7
8# 3. 批量归档（脚本化）
9for id in $(lark-cli doc search --query "归档" --format json | jq -r '.[].document_id'); do
10 lark-cli doc documents get --document_id $id --format markdown \
11 > "obsidian-vault/归档/$id.md"
12done
场景二：Obsidian → 飞书协作
1# 将 Obsidian 笔记上传到飞书
2lark-cli doc create --title "$(head -1 note.md | sed 's/^# //')" \
3 --content "$(cat note.md)"
场景三：用飞书多维表格管理选题
1# 本地管理选题，批量同步到飞书
2lark-cli base records append --table_id xxx --app_token yyy \
3 --fields "$(cat topic.json)"
第六章：Agent Skills（AI Agent 调用）
lark-cli 内置 26 个 Agent Skills，适合集成到 AI 工作流中：
| Skill | 用途 |
|---|---|
lark-calendar |
日历事件、议程、忙闲查询、会议室查找、RSVP |
lark-im |
发送/回复消息、群聊管理、表情回应 |
lark-doc |
文档 CRUD、搜索（基于 Markdown） |
lark-sheets |
电子表格创建/读取/写入/导出 |
lark-base |
多维表格字段/记录/视图/看板 |
lark-task |
任务/清单/提醒/成员分配 |
lark-mail |
邮件浏览/搜索/发送/回复/草稿 |
lark-vc |
会议记录、纪要（摘要/待办/全文） |
lark-okr |
OKR 查询/创建/更新/对齐 |
lark-approval |
审批查询/通过/拒绝/转交 |
lark-attendance |
考勤打卡记录查询 |
lark-skill-maker |
自定义 Skill 框架 |
常见问题
坑 1：CLI 返回 fetch failed
通常是网络问题，检查是否能访问飞书开放平台 API。如果使用了代理，确认代理配置正确。
坑 2：npx feishu 报 command not found
确认已执行 npx @larksuite/cli@latest install。如果使用 npx 临时调用，确保 npm 版本 ≥ 7。
坑 3：上传后飞书文档的引用块无法被 CLI 匹配
飞书文档的引用块在 Markdown 转换时可能走样。上传后可以在飞书 Web 端检查格式，手动调整。
坑 4：update 必须带 –new_title
更新文档时 --title 参数是必填的，即使标题不变也要显式传入。
坑 5：上传后的格式有问题
代码块丢失、表格变形等问题多出现在 Markdown 到飞书富文本的转换过程中。建议：
- 代码块使用标准围栏格式
``` - 表格保持简洁，避免合并单元格
- 上传后检查并手动修复
坑 6：一次上传多个文件时被限流
飞书开放平台 API 有频率限制。批量操作时建议：
- 使用
--page-delay参数控制请求间隔 - 分批上传，每次不超过 10 个文件
- 单个文件大小控制在 10MB 以内
附录：命令速查
1# 配置
2lark-cli config init # 初始化配置
3
4# 认证
5lark-cli auth login # 登录
6lark-cli auth status # 查看登录状态
7lark-cli auth logout # 登出
8lark-cli auth list # 列出所有已认证用户
9
10# 文档
11lark-cli doc create # 创建文档
12lark-cli doc get # 获取文档
13lark-cli doc update # 更新文档
14lark-cli doc search # 搜索文档
15
16# 日历
17lark-cli calendar +agenda # 查看议程
18lark-cli calendar list # 列出日历
19
20# 即时通讯
21lark-cli im +send # 发送消息
22lark-cli im messages list # 列出消息
23
24# 多维表格
25lark-cli base tables list # 列出表格
26lark-cli base records list # 列出记录
27lark-cli base records append # 新增记录
28
29# 知识库
30lark-cli wiki list # 列出知识库
31lark-cli wiki node get # 获取节点内容
32
33# 通用
34lark-cli api GET ... # 原始 API 调用
35lark-cli schema <method> # 查询 API 参数结构
36--dry-run # 预览模式
37--format json # 输出格式
写在最后
飞书 CLI 的价值不仅在于它提供了 200+ 命令，更在于它打通了"飞书内"和"飞书外"的边界。文档可以自由流向本地、多维表格可以被脚本批量操作、知识库可以纳入 CI/CD 流程。
对知识工作者来说，这意味着告别复制粘贴——用一行命令完成以前需要打开网页、点七八次鼠标才能完成的工作。
工具的价值不在于功能多少，而在于它能不能消失在你的工作流中。