飞书 CLI 到底是个啥？开发者常用的小工具核心用法

下载与安装步骤

飞书 CLI 其实不是什么神秘的东西，它就是飞书官方给开发者准备的一套命令行工具，说白了就是你打开终端敲命令就能操作飞书的各种功能。我第一次接触这玩意儿是在做内部机器人集成的时候，当时找下载入口找了好一会儿，最后在飞书开放平台的开发者文档里找到了下载包的链接。你去飞书开放平台官网，进到文档专区，搜索“CLI”关键词，就能看到下载页面，点本页下载按钮会弹出一个列表，有 macOS、Windows、Linux 三个版本。我用的 Mac，就下了个 dmg 文件，双击安装一路点“继续”就行，没啥难度。Windows 版是个 exe 安装包，下载后直接运行，装完后会自动加到系统路径里，你打开命令提示符敲 `lark-cli` 就能看到一大堆帮助信息。有朋友跟我说他装完敲命令没反应，后来发现是没重启终端，或者没把安装目录加到环境变量里——Windows 用户记得检查一下系统变量里的 PATH。Linux 版是个压缩包，解压后把可执行文件扔到 /usr/local/bin 目录下，权限给个 755 就行。安装完建议敲个 `lark-cli --version` 确认一下是否跑通，如果显示版本号就说明搞定了。

基本命令与机器人操作

飞书 CLI 最核心的用途就是管理机器人，特别是当你需要批量发消息或者搞自动化通知的时候。我记得有一回要写脚本每天定时给团队推送进度报告，用飞书 CLI 发消息简直就是开挂。基本用法是 `lark-cli send --to chat_id --msg "你的内容"`，但前提是你得先有个应用凭证。你需要在飞书开放平台创建一个应用，拿到 App ID 和 App Secret，然后在终端用 `lark-cli auth --app-id xxx --app-secret xxx` 登录认证。这里有个坑：chat_id 不是聊天组名称，而是一个字符串 ID，你可以在飞书群里找个 Webhook 机器人，发条消息后查看请求体里的“chat_id”字段。我第一次搞的时候直接复制了群名字进去，报错报了半天，后来才意识到得用飞书开放平台提供的调试工具查真实 ID。发消息还可以加富文本，比如 `--msg-type markdown` 参数就能解析 Markdown 格式，标题、列表、代码块都能展示。还有个 `--target` 参数可以指定是发到个人还是群聊，用户 ID 或者 open_id 都可以用。如果你只想测试一下，可以加个 `--dry-run` 参数，它会模拟发送但不真实推送，特别适合调试。

文件上传与管理场景

除了发消息，飞书 CLI 还能帮你上传文件到飞书云盘或者消息附件里，这对做自动化运维报告特别有用。我有次要把服务器上的日志文件扔到一个共享文件夹里，让同事能直接预览，不想手动拖拽，就用 `lark-cli upload --file /path/to/your/file.log --folder folder_token`。folder_token 是文件夹的唯一标识，你可以在飞书网页端打开文件夹，看地址栏的 folder_token 参数。如果没有指定文件夹，它会默认存到当前应用的文件空间。上传成功后返回一个文件 token，之后可以用 `lark-cli delete -token 你得到的token` 来清理。注意，飞书 CLI 对文件大小有限制，免费版单个文件不能超过 20MB，付费空间能到 1GB 左右，但传大文件容易超时，建议先压缩再传。我还遇到过传图片时预览不了的情况，后来发现是参数里没加 `--type image`，它默认当成普通文件处理了。如果你想批量上传，可以写个 shell 脚本循环处理，配合 `lark-cli upload` 的返回结果做日志记录，这样出问题了也能追查。

消息模板与定时任务

飞书 CLI 不只是能发简单文本，你还得学会搞消息模板，不然每次都要手写格式累死。飞书开放平台提供了一套消息卡片模板，你可以在开发者后台设计好模板，然后用 `lark-cli send --card-template template_id --variable key=value` 来填充变量。我做过一个天气预报机器人，模板里定好了城市、温度、天气状况三个变量字段，每天凌晨用 crontab 调用 CLI 命令，传入不同的参数值就能生成不同的卡片。比如 `lark-cli send -to 用户ID --card-template 123456 --variable city=北京 temperature=20 weather=晴`。模板里还可以加按钮、链接，交互性很强。定时任务的话，Linux 上直接加 crontab: `0 8 * * * /usr/local/bin/lark-cli send ...`，Windows 上可以用任务计划程序。但要注意：如果你的应用 token 会过期，定时任务里得先执行一次 `lark-cli auth` 刷新凭证。我踩过最大的坑就是 token 忘了更新，结果连续一周没发出去通知，群里的同事都以为我摸鱼去了。解决办法是把认证命令和发消息命令写到一个脚本里，先认证再发送，然后 crontab 直接跑这个脚本。

调试与日志查看

开发阶段免不了要折腾错误，飞书 CLI 提供了几个很实用的调试工具。你可以在命令后面加 `--verbose` 参数输出详细的请求日志，包括 HTTP 请求头和返回体，这对排查参数传错或者权限问题特别有用。我之前写过一条命令想发加急消息，多传了一个过期时间参数，接口一直返回 400 错误，打开 verbose 一看才发现是参数名拼错了。还有个命令叫 `lark-cli list --type event`，能列出你应用订阅的所有事件回调记录，比如新成员进群、消息被撤回等等。你可以看每条事件的状态码和响应时间，如果发现有失败记录，复制 event_id，然后用 `lark-cli trace -event=你的event_id` 去追踪处理过程。这个 trace 功能会一直轮询直到返回完整日志，相当于一个实时的追踪器。不过 trace 命令最多只能查最近 3 天的事件，老数据得去开放平台的后台日志页面看。另外，如果你用的是 Windows 系统，CMD 终端乱码是常有的事，建议用 Windows Terminal 或者直接在 PowerShell 里跑，编码问题少得多。

权限与安全配置

飞书 CLI 的权限管理有时候比你想的复杂，因为每个命令都依赖于应用在开放平台配置的权限范围。比如说你给应用只开通了“发消息”权限，但想用 CLI 上传文件，就会直接报“permission denied”。你去飞书开放平台的应用后台，在“权限管理”模块找到对应的权限并申请开通，开通后一般 5 分钟内生效。CLI 本身有个 `lark-cli check-permission` 命令可以列出当前应用已有的所有权限，省得你自己去网站翻。提醒一句：千万不要把你的 App Secret 硬编码在脚本里，尤其是把脚本上传到公共仓库。我见过有人直接在 GitHub 上 commit 了密钥，结果被爬虫扫到了，应用频繁被其他人调用，吓得赶紧重置密钥。安全点的做法是用环境变量保存，比如执行 `export LARK_APP_SECRET=你的密钥`，然后在 CLI 命令里引用环境变量。飞书 CLI 还支持使用 OAuth 授权码模式，如果你不想长期保存密钥，可以每次通过跳转浏览器登录获取临时 token，这样更安全，但自动化就不太方便了。

常见坑与实用技巧

用了飞书 CLI 大半年，攒了一些踩坑记录和见效的小技巧。第一个是发消息时中文内容乱码的问题，特别是 Windows 上，默认编码是 GBK 而飞书接口只认 UTF-8。解决方法是在命令前加一句 `chcp 65001` 把终端编码切到 UTF-8，或者把消息内容存到文本文件里然后用 `--msg-file` 参数读取，文件保存成 UTF-8 无 BOM 格式。第二个坑是 batch send 时容易触发限流，飞书 API 对单个应用每分钟有 600 次请求限制，超过了就返回 429。你要是给几百人发消息，建议用 `lark-cli send --batch` 并设置 `--interval 200` 毫秒的间隔。第三个技巧：没事儿多翻翻飞书 CLI 的 `--help` 输出，很多隐藏参数比如 `--force-ssl` 能在 HTTPS 不稳定的网络环境强制使用 SSL 连接，或者 `--timeout 300` 能延长请求超时时间，传大文件时绝对管用。还有个冷知识：你可以在执行 CLI 命令的同时用 `jq` 工具解析返回的 JSON，比如 `lark-cli list --type user | jq '.data.items[] | {name, open_id}'`，这样直接就能把用户信息导出成表格。最后提醒一句：飞书 CLI 不是万能的，如果你需要开发复杂的交互流程，比如多轮对话或者审批流，还是得用飞书开放平台提供的 SDK 编写代码，CLI 更适合做快速脚本和自动化运维。