1. 飞书 CLI 到底是什么为什么值得花时间学第一次听到“飞书 CLI”这个词大概率是在某个技术群里看到有人发了一张终端截图里面几行命令跑完多维表格的数据就批量更新了或者一条消息就推到了群里。当时我的反应是这东西听起来挺酷但跟我平时用飞书的方式好像没什么交集。直到后来接手了一个需要频繁操作飞书文档和表格的项目手动点击的效率实在撑不住才真正开始认真研究 lark-cli 这套工具。飞书 CLI简单说就是把飞书开放平台的 API 能力封装成命令行工具让你在终端里直接操作飞书的各种资源——发消息、读写多维表格、管理云文档、处理审批流等等。它的核心价值在于把重复性的操作自动化把原本需要在网页端点击十几次的流程压缩成一行命令。适合谁学如果你日常工作中需要批量处理飞书表格数据、需要把飞书和其他系统做轻量级集成、或者单纯想提升自己的工具链效率那 CLI 这条路值得走一遍。我一开始也以为这东西门槛很高毕竟“命令行”三个字对很多非科班出身的人来说天然有距离感。但实际用下来发现lark-cli 的设计思路是尽量降低使用门槛的——安装方式简单认证流程清晰常用操作都有对应的子命令。你不需要精通 shell 脚本只需要理解基本的命令结构就能完成大部分日常操作。当然如果你想把它用出花来那确实需要一些编程基础比如用 Python 或 Node.js 写脚本调用 CLI 的输出结果做二次处理。这篇文章我会从零开始把飞书 CLI 的安装、认证、核心功能、实操案例、常见坑点全部串一遍。不会只讲“怎么装”而是把每个步骤背后的逻辑讲清楚让你知道为什么这么做、不这么做会怎样。文章里涉及的具体命令和参数我会尽量给出可直接复制的版本同时说明每个参数的含义方便你根据自己的场景调整。2. 安装与环境准备选对方式少走弯路2.1 不同操作系统的安装方案对比lark-cli 的安装方式取决于你的操作系统和已有的开发环境。官方提供了几种主流方式我逐一试过之后整理了一张对比表安装方式适用系统前置依赖优点缺点npm 全局安装Windows/macOS/LinuxNode.js 16版本管理方便升级简单需要先装 Node.js 环境二进制包下载Windows/macOS/Linux无开箱即用不依赖运行时手动更新需自己管理 PATHHomebrewmacOS/LinuxHomebrew一条命令搞定仅限已装 Homebrew 的用户源码编译全平台Go 1.20可定制最新特性门槛高编译可能报错我个人推荐 npm 方式原因是版本更新最及时而且如果你已经在做前端或 Node.js 相关的开发环境本身就是现成的。Windows 用户如果不想装 Node.js直接下载二进制包也完全可行解压后把目录加到系统 PATH 里就能用。安装完成后在终端执行lark-cli --version如果能正常输出版本号说明安装成功。这一步看似简单但我见过不少人卡在这里——要么是 PATH 没配好要么是权限问题导致命令找不到。Windows 上还有一个常见情况用 PowerShell 和 CMD 的结果可能不一样建议统一用 PowerShell 或 Windows Terminal避免环境变量读取不一致的问题。2.2 认证配置理解 Token 机制是关键安装只是第一步真正让 CLI 能操作你的飞书资源需要完成认证配置。飞书开放平台的认证体系基于应用凭证你需要先在飞书开放平台创建一个应用拿到 App ID 和 App Secret然后通过 CLI 完成授权。具体流程是这样的首先在飞书开放平台后台创建企业自建应用开通需要的权限比如消息发送、多维表格读写、云文档管理等然后拿到 App ID 和 App Secret。接着在终端执行认证命令把这两个凭证配置进去。CLI 会帮你换取 access token后续所有操作都基于这个 token 进行鉴权。这里有个关键点很多人会忽略token 是有有效期的。飞书的 tenant access token 默认有效期是两小时过期后需要重新获取。lark-cli 内部做了自动刷新的逻辑但前提是你的 App Secret 配置正确且应用没有被停用。如果你发现命令突然报鉴权失败第一反应应该是检查应用状态和凭证是否有效而不是怀疑命令写错了。另一个容易踩的坑是权限范围。飞书应用的权限是细粒度的你开通了什么权限CLI 就能做什么操作。比如你想读写多维表格就必须开通bitable:app相关的权限想发消息就需要im:message权限。权限没开通的情况下CLI 会返回明确的错误码告诉你缺少哪个权限。我建议在开发阶段先把常用权限都勾上避免反复调整。注意App Secret 是敏感信息不要直接写在脚本里提交到代码仓库。建议用环境变量或配置文件的方式管理CLI 支持从环境变量读取凭证。2.3 配置文件的位置与优先级lark-cli 支持多种配置来源优先级从高到低大致是命令行参数 环境变量 配置文件 默认值。配置文件通常放在用户目录下的.lark-cli目录里里面记录了你的应用凭证、默认的表格 token、常用参数等。我习惯把不同项目的配置分开管理比如用不同的配置文件路径通过--config参数指定。这样切换项目时不会互相干扰。如果你同时管理多个飞书应用这个做法尤其有用。配置文件的格式一般是 YAML 或 JSON具体取决于 CLI 版本。我建议第一次配置时用交互式命令引导完成生成的文件结构清晰后续手动修改也不容易出错。3. 核心功能拆解从发消息到操作多维表格3.1 消息发送最基础也最常用的能力用 CLI 发消息到飞书群或私聊是最直观的入门操作。基本命令结构是lark-cli im send加上目标 ID 和消息内容。目标 ID 可以是群聊的 chat_id也可以是用户的 open_id 或 user_id。消息类型支持文本、富文本、卡片、图片、文件等。文本消息最简单直接传字符串就行。富文本和卡片消息需要构造 JSON 结构灵活性更高但上手成本也更高。我建议先从文本消息开始跑通流程后再尝试卡片消息。这里有个实操细节群聊的 chat_id 怎么获取。如果你在网页端看群设置是看不到 chat_id 的。获取方式有两种一种是通过 CLI 的群列表命令查询另一种是在群内添加一个机器人通过机器人接收到的消息事件里拿到 chat_id。前者更直接后者适合需要动态获取的场景。发送消息时还有一个常见需求是 某人。在文本消息里 的格式是at user_idou_xxx名字/at其中 user_id 是用户的 open_id。这个格式在飞书的消息协议里有明确定义但第一次用的人往往会写成名字这种自然语言形式结果发出去就是纯文本不会触发真正的 提醒。3.2 多维表格操作CLI 的高频使用场景多维表格是飞书里用得最多的协作工具之一也是 CLI 操作频率最高的对象。通过 CLI 可以完成记录的新增、查询、更新、删除以及字段的读取和表格元数据的管理。操作多维表格需要两个核心标识app_token 和 table_id。app_token 是多维表格的唯一标识可以从表格的 URL 里提取table_id 是具体数据表的标识同样可以从 URL 或通过 CLI 查询获得。新增记录的命令大致是lark-cli bitable record create需要指定 app_token、table_id 和字段数据。字段数据是一个 JSON 对象key 是字段名value 是字段值。不同类型的字段value 的格式不一样——文本字段直接传字符串单选字段传选项名日期字段传时间戳人员字段传用户 ID 数组。这个格式如果搞错了CLI 会报参数错误但错误信息有时候不够直观需要你对照文档排查。查询记录支持过滤条件、排序、分页等参数。过滤条件的语法是飞书特有的表达式格式比如CurrentValue.[字段名] 值。这个语法第一次接触会觉得有点绕但用几次就熟悉了。分页参数在数据量大时很重要默认每页返回的记录数有限需要用 page_token 逐页获取。批量操作是 CLI 相比手动点击的最大优势。比如你要更新一百条记录的某个字段用 CLI 写个循环几秒钟就跑完了。手动操作的话一百条记录点下来至少半小时起步。3.3 云文档与审批流进阶但实用的能力除了消息和多维表格CLI 还支持云文档的创建、读取、内容更新以及审批流的发起和查询。云文档操作的核心是 document_id可以通过创建文档命令获取也可以从已有文档的 URL 里提取。审批流的操作相对复杂一些因为审批涉及审批定义、审批实例、审批任务等多个概念。CLI 提供了对应的子命令但使用前需要先理解飞书审批的模型。如果你只是偶尔发起一个审批用网页端可能更快但如果你需要批量发起审批或者把审批集成到自动化流程里CLI 的价值就体现出来了。我在实际项目里用得最多的组合是用 CLI 读取多维表格的数据处理后写回另一个表格同时发消息通知相关人员。这个流程如果用网页端操作每天至少要花二十分钟用 CLI 写成脚本后一条命令几秒钟搞定。4. 实操案例从零搭建一个自动化流程4.1 场景描述与方案设计假设你有一个需求每天定时从某个多维表格里读取当天新增的订单记录汇总后发送到飞书群里同时把汇总数据写入另一个表格。这个需求用 CLI 可以完整实现。方案设计上我把它拆成三步第一步用 CLI 查询源表格中符合条件的数据第二步对查询结果做汇总处理第三步把汇总结果发消息到群里并写入目标表格。每一步都对应 CLI 的具体命令中间的数据处理可以用 shell 脚本或 Python 脚本完成。选择 CLI 而不是直接调 API 的原因是CLI 已经封装了认证、请求构造、错误处理等逻辑你只需要关注业务层面的参数。对于不熟悉 HTTP 请求和 JSON 处理的人来说CLI 的上手成本明显更低。4.2 分步实现与命令详解第一步查询源表格数据。命令如下lark-cli bitable record list \ --app-token your_app_token \ --table-id your_table_id \ --filter CurrentValue.[创建时间] \2025-01-01\ \ --page-size 100这里--filter参数指定了过滤条件--page-size控制每页返回的记录数。返回结果是 JSON 格式包含记录列表和分页信息。第二步处理返回数据。如果记录数超过一页需要循环获取所有页。可以用 jq 工具提取字段或者用 Python 脚本解析 JSON。我通常用 Python因为处理逻辑更灵活。第三步发送消息和写入目标表格。发送消息的命令lark-cli im send \ --receive-id oc_xxx \ --receive-id-type chat_id \ --msg-type text \ --content {text: 今日订单汇总共 25 单总金额 12800 元}写入目标表格的命令lark-cli bitable record create \ --app-token target_app_token \ --table-id target_table_id \ --fields {日期: 2025-01-01, 订单数: 25, 总金额: 12800}把这三步串成一个脚本加上定时任务整个流程就自动化了。4.3 参数计算与选择依据在查询数据时--page-size的设置需要权衡。设得太小请求次数多效率低设得太大单次响应数据量大处理慢。飞书多维表格 API 的单页上限通常是 500 条我一般设 100 到 200兼顾效率和响应速度。过滤条件里的时间格式需要注意。飞书多维表格的日期字段在 API 里通常以时间戳形式存储但过滤表达式里可以用可读的日期字符串。具体格式取决于字段的配置建议先用一条已知记录测试过滤条件是否正确。消息内容的长度也有限制。文本消息最大长度是 150KB一般汇总信息不会超。但如果你的汇总内容很长建议用卡片消息或者拆成多条发送。5. 常见问题与排查技巧实录5.1 认证失败与权限不足的排查思路认证失败是最常见的问题表现通常是命令返回 401 或 403 错误码。排查顺序建议是先确认 App ID 和 App Secret 是否正确再确认应用是否已发布或启用然后检查所需权限是否已开通。有一个容易忽略的点应用版本。飞书应用有测试版本和正式版本之分测试版本的权限变更不需要审核但只在测试企业生效。如果你在测试企业里调试好了切换到正式企业时发现权限不对很可能是因为正式版本没有同步开通对应权限。权限不足的错误信息通常会告诉你缺少哪个权限但有时候错误码比较笼统。这时候可以到飞书开放平台的 API 调试台里用相同的参数手动调一次看返回的详细错误信息。调试台的错误提示比 CLI 更详细适合排查复杂问题。5.2 数据格式错误与字段类型不匹配多维表格的字段类型很多每种类型在 API 里的数据格式都不一样。文本字段传字符串数字字段传数值单选字段传选项名字符串多选字段传选项名数组日期字段传毫秒时间戳人员字段传 open_id 数组附件字段传文件 token 数组。我踩过的一个坑是日期字段传了字符串格式的日期结果 CLI 报错说格式不对。后来查文档才知道日期字段在 API 里必须传毫秒时间戳。转换方法是用date %s000命令生成当前时间的毫秒时间戳或者用编程语言里的时间函数处理。另一个坑是单选字段。如果传的值不在选项列表里API 会报错。但错误信息不一定明确告诉你“选项不存在”而是返回一个通用的参数错误。排查方法是先查询表格的字段元数据确认选项列表再对照传入的值。5.3 分页与大数据量处理的注意事项当表格数据量很大时分页处理是必须的。CLI 的查询命令默认只返回第一页需要用--page-token参数逐页获取。page_token 从上一页的返回结果里提取每次请求都要带上。这里有个细节page_token 是有有效期的。如果两页请求之间间隔太久page_token 可能过期需要重新从第一页开始。所以在写循环脚本时建议尽快完成所有页的请求不要在中途做耗时操作。另外频繁请求可能会触发飞书的限流。飞书 API 有调用频率限制具体阈值取决于接口类型。如果遇到 429 错误码说明被限流了需要降低请求频率或增加重试逻辑。我一般会在脚本里加一个简单的 sleep每请求一页暂停 200 毫秒实测下来很少触发限流。5.4 常见问题速查表问题现象可能原因排查方法解决方案命令找不到PATH 未配置执行which lark-cli把安装目录加入 PATH401 鉴权失败凭证错误或过期检查 App ID/Secret重新配置凭证403 权限不足未开通对应权限查看错误信息中的权限码在开放平台开通权限字段格式错误字段类型不匹配查询字段元数据按类型转换数据格式分页数据不全未处理 page_token检查返回的 has_more循环获取所有页429 限流请求频率过高查看错误码降低频率或加重试消息发送失败receive_id 类型错误确认 ID 类型指定正确的 receive_id_type6. 进阶技巧与效率提升6.1 用脚本封装常用操作CLI 的命令虽然简洁但每次都要输入一长串参数也挺烦的。我习惯把常用操作封装成 shell 函数或 Python 脚本用简短的别名调用。比如把“查询今日订单并汇总”封装成一个命令每天只需要执行一次就行。封装时要注意参数的可配置性。不要把 app_token、table_id 这些硬编码在脚本里而是通过参数或环境变量传入。这样同一个脚本可以用在不同的表格上复用性更高。6.2 与其他工具的联动lark-cli 的输出是标准 JSON这意味着它可以很方便地和其他命令行工具联动。比如用 jq 提取字段、用 awk 做统计、用 curl 转发到其他系统。我经常用 jq 配合 CLI快速从返回结果里提取需要的字段省去写解析代码的麻烦。如果你在用 CI/CD 工具也可以把 CLI 集成到流水线里。比如代码合并后自动发飞书通知或者定时同步数据到多维表格。CLI 的退出码遵循标准约定成功返回 0失败返回非 0方便流水线判断执行结果。6.3 性能优化的几个实操心得批量操作时能合并的请求尽量合并。比如新增记录CLI 支持一次传多条记录比循环单条新增快得多。具体上限取决于接口一般是 500 条一次。查询时尽量用过滤条件缩小范围不要全表拉取后再过滤。飞书的过滤是在服务端执行的能有效减少返回的数据量。如果过滤条件复杂可以分多次查询再合并结果。缓存不常变的数据。比如字段元数据、表格结构这些信息不需要每次操作都查询。可以在脚本启动时查一次缓存到本地文件或内存里后续直接使用。7. 我个人在实际操作中的体会飞书 CLI 这个工具入门门槛不高但要用得顺手需要一些积累。我最初只是用它发发消息后来逐渐扩展到多维表格操作和自动化流程。最大的感受是它把很多原本需要写完整 API 调用代码的场景简化成了一行命令。对于不擅长编程但又有自动化需求的运营、产品岗位来说这是一个很实用的切入点。踩过的坑主要集中在权限配置和数据格式上。权限这块建议一开始就把可能用到的权限都开通避免中途反复调整。数据格式这块遇到报错先查字段元数据确认类型后再传值能省很多排查时间。另外CLI 的版本更新比较频繁新功能会陆续加进来。建议定期用包管理工具升级到最新版本同时关注更新日志里的变更说明。有些命令的参数在新版本里可能有调整升级后如果发现原来的脚本报错先检查是不是参数格式变了。最后分享一个小技巧如果你不确定某个命令的参数怎么写可以用--help查看详细说明。CLI 的帮助信息写得比较清楚包含参数说明和示例比翻文档快。
