飞书 CLI 从听说到入门

「从听说到入门」系列第三篇。主角是飞书 CLI（lark-cli）——飞书官方开源的命令行工具。这一篇我既是地图作者也是重度用户：这个站的飞书文档同步、我的固定文档更新，每天都是从终端里敲出去的。

一、它是干什么的

lark-cli 是飞书官方（larksuite 团队）开源的命令行工具，用 Go 编写、MIT 协议，GitHub 仓库 larksuite/cli，官方介绍页在 feishu.cn/feishu-cli。一句话说清楚它：让你（以及 AI Agent）在终端里直接操作飞书——读写文档、增查多维表格、发消息、管日历、搜邮件，不用打开浏览器点界面。要理解它的位置，得先知道飞书开放平台：飞书把几乎所有产品能力都开放成了 API（2500 多个 OpenAPI），普通玩法是写代码调接口，而 lark-cli 把「建应用、拿凭证、算签名、发请求、解析返回」这些样板工作全部封装掉，变成一条条敲得出来的命令。它在这个生态里的位置是这样的：

所以它和开放平台的关系一句话就能说清：lark-cli 不是另一个平台，是飞书 OpenAPI 的「命令行皮肤」——认证、调用、输出全部套在开放平台之上。官方还专门为 AI Agent 做了调优：26 个开箱即用的 Agent Skills，适配 Claude Code 这类工具，Agent 装上就能替你操作飞书。

二、核心概念速览

三层命令架构是它最值得讲的设计，从上到下覆盖三种人：快捷命令给人和 Agent 用，参数友好带智能默认值，比如 lark-cli docs +create；API 命令从官方接口元数据自动生成，与开放平台端点一一对应，平台更新它跟着更新；通用调用 lark-cli api GET/POST + 路径 兜底，理论上 2500 多个 API 都能调。用的时候记一个原则：先用快捷命令，不够再往下走。

三、典型工作流：从安装到自动化

前三步是一次性的，做完终身受用：

npx @larksuite/cli@latest install
lark-cli config init
lark-cli auth login --recommend
lark-cli calendar +agenda

第四步 config init 会交互式引导你去飞书开放平台建一个应用——自建应用免费，十分钟拿一对 app_id 和 app_secret，这是飞书生态里被低估的免费资源。auth login --recommend 自动勾选常用权限，浏览器里点同意即可；--recommend 之外也可以 --scope 精确指定，拿不准就先 auth check 校验某个 scope 有没有。日常读写长这样：

lark-cli docs +create --doc-format markdown --content "标题"
lark-cli docs +update --command append --doc-format markdown --content @file.md
lark-cli bitable records list --app-token xxx --table-id xxx
lark-cli im +messages-send --chat-id oc_xxx --text "跑完了"

最后一步是把它拼进自动化：我的固定飞书文档更新就是「本地生成 markdown → docs +update 追加 → 解析返回确认成功」三行脚本。写脚本时用 --format json，判断成功认 ok 字段——这是 lark-cli 自己的输出契约，与开放平台原始返回的 code == 0 不同，判断错了脚本会静默失败。

四、常见坑与入门建议

• 权限不够先查 scope：命令报权限错误，先跑 auth status 看已授权范围，补授权重跑，别反复试错。
• 身份搞混：有些操作必须用户身份，有些必须机器人身份。结果不对时先确认 --as 参数。
• 写操作先 --dry-run：发消息、改文档这类有副作用的命令，官方提供 dry-run 预览请求，AI Agent 批量操作前尤其建议先看一眼。
• 别把授权当儿戏：官方风险提示写得很直白——授权后 Agent 以你的身份在权限范围内操作，存在幻觉执行、提示词注入等风险。建议机器人做私人助手用，别拉大群、别一次授全量权限。
• 列表类命令记得分页：--page-all 自动翻页拿全量，漏了它就只拿到第一页，还以为数据就这么多。
• 入门建议：从一件小事开始——把每周要写的工作周报做成「脚本生成 markdown → lark-cli 追加进飞书文档」。第一次跑通大概一个晚上，之后你就有了一个可以无限复用的模式。

五、可以带走的方法

1. 三层调用是渐进式学习地图：快捷命令覆盖九成日常，不够再查 lark-cli schema 自省参数，最后才用通用 api 调用兜底。
2. 自动化 = 契约思维：把「命令执行成功」定义成程序可判断的条件（ok 字段），这一步想通，任何 CLI 工具都能拼进你的流水线。
3. 开放平台思维比工具本身更值钱：学会用 lark-cli 之后你会发现，飞书里的文档、表格、审批、消息都成了脚本可操作的资源——这是从「用软件」到「编排软件」的转变。

---

后续会把自己用 lark-cli 搭的实战小工具补进这篇：飞书文档自动同步管道、多维表格当轻量数据库的用法、以及配合 AI Agent 的几条真实工作流，都会落成可复现的步骤。

——胡安，格致笔记站长。制造业品类管理数字化十八年，自学编程的「工具原生问题解决者」，lark-cli 是我每天在用的主力工具之一，这篇会随着我的用法一起生长。