飞书CLI命令行工具怎么用，写给程序员的手册

下载与安装：从下载站拿到 CLI 程序

先说说怎么把这玩意儿搞到手。你去飞书下载站，点本页下载按钮，会看到一个压缩包，里头就是飞书 CLI 的二进制文件。我头一回下载时还以为是啥全家桶安装包，结果解压出来就一个可执行文件，名字叫 feishu 或者 lark-cli，看版本不同可能有点区别。建议直接扔到 /usr/local/bin 或者 C:WindowsSystem32 里，这样全局就能调用了。记得给执行权限，Linux 和 macOS 下用 chmod +x，Windows 默认就可以。下载站通常只提供最新版，不会有历史版本选择，别想着去找旧版，除非你翻了官方文档的归档页面。我踩过一个坑：下载完直接跑了个 feishu -h，结果显示 command not found，后来发现是环境变量 PATH 没配好，你要是用 zsh 记得检查一下 .zshrc 里有没有加。

安装包不大，大概十几兆的样子，比我想象的小很多，毕竟就是个命令行工具。你要是用 macOS，注意一下安全提示，系统可能会跳出来说“无法验证开发者”，去系统偏好设置里手动允许一下就完事。Windows 的话，杀毒软件可能会报敏感行为，原因是 CLI 工具会调网络请求，加个信任就行。解压后最好别直接双击运行，这又不是 GUI 程序，双击只会闪一下黑框。你得打开终端或者 PowerShell，然后 cd 到那个目录，或者像我一样直接扔进 PATH 里用。首次运行我建议先执行 feishu version 看安装成功没，输出个版本号就稳了。如果没输出，检查下载的文件是不是被截断了，有些下载站会偷偷改名，把你下载的文件改成了 feishu.zip.zip，很坑。

配置登录：拿 Token 还是用 OAuth

装好后第一步是登录。飞书 CLI 支持两种方式：个人 Token 和 OAuth。我推荐开发者在测试环境用 Token，生产环境用 OAuth。配置命令很简单，feishu config set token your_personal_token，这个 Token 你得去飞书开放平台的开发者后台里生成，路径通常是“应用凭证”或者“权限管理”里。注意，Token 有有效期，一般是 72 小时，过期后 CLI 会报 401 错误，到时候得重新生成。我头回用的时候没注意有效期，写了个自动化脚本每天跑，结果第三天突然全挂了，排查半天才发现是 Token 过期。

OAuth 配置稍微复杂一点，但你团队里多人共用时更安全。执行 feishu auth login，它会弹出一个浏览器窗口让你授权，选好应用就自动绑定。这里有个细节：CLI 需要本地开启一个临时重定向端口，默认是 8080，如果端口被占用了，会报端口冲突。解决办法是手动指定别的端口，feishu auth login --port 9090。另外，如果你在远程服务器上操作，没有浏览器窗口咋办？可以用 headless 模式：feishu auth login --no-browser，然后它会打印一个链接，你在本地浏览器打开授权就行，授权码复制回来粘贴。登录成功后，CLI 会把凭证存到 ~/.config/feishu 目录下，别手贱删了它。

核心命令：发消息、查群聊和上传文件

登录完了就可以干活了。先看几个高频操作。发消息是 feishu message send，我常用它来给团队的机器人频道发部署通知。比如 feishu message send --receiver chat_id:oc_xxx --msg_type text --content "服务已重启完成"。注意，chat_id 不是群名，你得从飞书管理后台的群聊信息里找，或者用 feishu chat list 先列出你的群。我一开始老用群名，结果总报“无效接收方”。另外一个注意事项：消息内容如果包含中文，最好用双引号括起来，不然 shell 可能会把空格当分隔符。

查群聊列表，feishu chat list 会返回所有群的 ID、名称和成员数。如果你想批量操作，比如向多个群发消息，可以先把列表保存在 JSON 文件里，再用脚本循环处理。我写过一个小工具，每晚自动汇总日志并推送到所有开发群，原理就是用 chat list 拿 ID 列表，然后 message send 挨个发。上传文件是另一个常用功能，feishu file upload --file_type stream --file_name debug.log --file_path ~/logs/debug.log，文件类型可以是 stream、sheet、doc 等等。上传后返回一个 file_key，你以后发消息时可以引用它。有个坑：文件最大 30MB，超过会报错，你得提前分割或者压缩。

应用管理与调试：创建、更新和查看日志

CLI 的一个重要用途是管理飞书应用。你可以用 feishu app create --name "MyApp" --desc "测试应用" 快速创建一个空应用，它会返回 app_id 和 app_secret。但要注意，这创建的是未发布的应用，只能在测试环境下用。如果你要更新应用配置，比如改描述或权限，用 feishu app update --app_id cli_xxx --desc "新描述"。权限变更通常需要重新发布才会生效，CLI 里有 feishu app publish 命令，执行后会自动走发布流程。我工作里最常用的是 feishu app version list 来查看所有历史版本，用 feishu app version rollback --version_id v1.0.2 来回滚到某个版本，这在线上出 bug 时非常救命。

调试应用时，日志查看很关键。feishu log tail --app_id cli_xxx 会实时输出应用运行日志，类似 tail -f 的效果。日志级别可以过滤，feishu log tail --level error 只看错误。如果你在本地调试 API，CLI 还能模拟请求，feishu api call --api_path /open-apis/im/v1/messages --method POST --body '{"receive_id":"xxx"}'。这个功能省去了每次写 curl 的麻烦，而且自动处理了签名和 Token。记得，模拟请求时别用生产环境的应用 ID，不然可能污染真实数据。

自定义扩展：脚本和 Hook 的玩法

CLI 不止是官方命令，它支持配置别名和扩展脚本。比如你每次都要发一条固定格式的消息，可以写个别名：feishu alias set "deploy-notify" "message send --receiver chat_id:xxx --msg_type text --content 已部署到生产"。以后直接用 feishu deploy-notify 就行，少敲很多字。别名存在 ~/.feishu/aliases.yaml 里，你可以手动编辑加新别名。另一个实用技巧是搭配 CI/CD 的 Hook：在 GitLab CI 或 GitHub Actions 里，用飞书 CLI 发通知。我的做法是写个脚本，构建成功后跑 feishu message send，失败时跑 feishu message send --content 构建失败，这样团队能第一时间知道。

如果你需要更复杂的逻辑，可以写 Python 或 Shell 脚本调用 CLI，比如从文件中读取聊天 ID 列表循环发送。但要注意 CLI 的并发限制，官方说是每秒 5 次请求，超过会限流。我踩过这个坑，脚本一次性发了 100 条消息，结果后面全被拦了，等了足足一分钟才恢复。解决方案是加 sleep 0.2 的间隔。还有个进阶用法：用 feishu event subscribe --type message.receive_v1 来监听事件，CLI 会挂起并打印监听到的事件 JSON，你可以把它重定向到文件再解析，适合调试 webhook 回调。这个功能默认只监听从关联应用发出的消息，别用来抓别人聊天内容，那是违规的。

常见报错与调试经验

用久了会发现几个老问题。第一个是“Invalid Signature”，多半是 Token 过期或者应用密钥配错了。你先检查一下 feishu config show 输出的 token 是不是最新的，密钥有没有被写入环境变量覆盖。第二个是“Network Error”，这时先 ping api.feishu.cn 看通不通，不通的话可能是公司网络有代理。CLI 支持代理配置：feishu config set proxy http://127.0.0.1:7890。我公司就用代理才能访问飞书 API，不配的话啥都跑不了。第三个是“Rate Limit Exceeded”，别慌，停一停再试。CLI 默认没限流机制，所以你自己得在脚本里控制频率，比如每次请求后 sleep 0.5 秒。

还有一个冷门错误：在 Windows 上用 PowerShell，CLI 输出的中文会乱码。解决方案是用 chcp 65001 把编码改成 UTF-8，或者直接换到 Windows Terminal 里跑。macOS 上偶尔遇到“zsh: killed”，是因为 CLI 被系统保护机制杀掉的，关闭 SIP 或者重新签名一下。我个人经验，多数问题就是 Token 失效和网络不通，排查时先执行 feishu config show 和 feishu ping，比翻文档快十倍。

安全与清理：退出登录和证书注意

最后讲一下收尾工作。退出登录用 feishu auth logout，这会清除本地保存的凭证。如果你是在共享机器上用，记得每次用完就登出，不然别人可以直接用你的身份发消息。另外，CLI 会在 ~/.feishu 目录下缓存一些临时文件，比如应用列表和日志，你可以手动删除这个目录来彻底清理。但别删掉 /usr/local/bin 里的二进制文件，除非你想卸载。

关于安全，有个细节：CLI 访问飞书 API 时用的是 HTTPS，默认验证证书。如果你在内部测试环境里搞了个自签证书，CLI 会报 SSL 错误。解决办法是加个参数跳过验证，feishu config set insecure true，但千万别在生产环境用。我见到过有人在 CI 脚本里写死 insecure true，结果被安全扫描器直报警告。还有，别把 Token 硬编码在版本控制里，可以用环境变量：export FEISHU_TOKEN=xxx，CLI 会自动读。如果你不小心把 Token 泄露了，立刻去开放平台撤销它，然后在 CLI 里重新配置。安全的习惯是每天下班前清一次 Token 缓存，尤其是你开了很多测试环境任务时。