飞书 CLI 是什么工具，怎么下载和使用
飞书 CLI 到底是个啥工具
前阵子我折腾自动化办公，想把飞书文档和代码仓库打通，才发现官方藏了个好东西——飞书 CLI。刚开始我也蒙，CLI 不就是命令行工具嘛，飞书出这玩意儿干啥。实际用下来发现，它就是个让你不用打开浏览器、直接在终端里操作飞书各种功能的工具包。比如自动发消息、管理日历事件、拉取文档内容，甚至还能跟 Jenkins 或者 GitHub Actions 结合，搞一套自动化通知和报表生成。
我个人觉得，这工具最适合两类人：一类是开发运维，想把飞书消息集成到部署流程里；另一类是重度办公用户，每天要重复处理飞书上的若干机械操作，比如批量拉取某个多维表格数据。飞书 CLI 本质是个轻量级的二进制文件，核心逻辑就是通过调用飞书 Open API，把那些本来要手点界面的操作变成一行命令。你也不用担心不会写代码，它自带了很多预设命令，跑起来跟用普通系统命令差不多。
下载与安装步骤
下载这事儿其实挺直接。我当初是去飞书官方开放平台的下载站找到的，你点本页下载按钮就能拿到适合你系统的安装包。Windows 用户拿到的通常是 .exe 或 .msi 文件，Mac 上一般是 .pkg 或者直接塞一个二进制到 /usr/local/bin。Linux 用户常见的是解压即用的 tar.gz 包。我建议千万别去第三方的软件站乱下，官方版体积小还干净，不会有啥捆绑。
安装方法看系统。Windows 上双击跑完安装向导就行，我习惯勾上“添加到 PATH”，这样后面在 PowerShell 或者 CMD 里直接敲 lark 或者 feishu 就能用。Mac 用户点 pkg 一路下一步，完成后可以在终端试试 `lark --version` 看看版本。Linux 的话我更喜欢手动解压后把那个二进制扔到 /usr/local/bin 再改个权限 `chmod +x`，这样所有用户都能调用。我当时踩过一个坑——Mac 上没注意安全设置，系统拦着不让运行，需要去“隐私与安全性”里点允许，或者跑 `spctl --master-disable` 把策略关了。
装完后第一件事就是配置 Token。飞书 CLI 本质是拿你应用的身份去调接口，所以你得先去开放平台创建一个应用，拿到 App ID 和 App Secret。我习惯在环境变量里配，比如 `export FEISHU_APP_ID=xxx`，再 `export FEISHU_APP_SECRET=yyy`，CLI 会自动读。你也可以直接在命令行里 `-app-id` 和 `-app-secret` 参数传，但那个容易暴露在历史记录里，我一般不这么干。配好之后跑个 `lark auth test` 验证一下，返回个“Hello, your app is valid”就对了。
核心命令与日常用法
飞书 CLI 的命令分层挺清晰，我常用的就几类。发消息是最直接的：`lark message send --receiver=ou_xxxx --msg_type=text --content="你好世界"`。这个 receiver 到底是用户还是群，刚开始我老搞混。实际上飞书用 open_id 来标识用户，chat_id 来标识群聊。你可以先用 `lark user search --email=xxx@company.com` 把你的同事找出来，看他的 open_id 是啥。群聊的 chat_id 更简单，在飞书群里 @机器人发一句“获取群 ID”，机器人就会告诉你。我一般把常用的人员 ID 写到一个 shell 脚本里，每次直接用变量。
文档操作也实用。`lark doc get --doc_token=xxxx` 能把飞书文档全文拉下来，默认是 Markdown 格式，正好丢进知识库或者 Git 仓库里做版本管理。有些时候我想把多维表格的数据导出成 CSV，命令就是 `lark sheet export --spreadsheet_token=xxxx`，跑完会在当前目录生成一个 .csv 文件。还有个命令我不常用但关键时刻救命：`lark calendar create --summary="周会" --start_time="2024-01-15T10:00:00"`，可以直接从终端往你日历里塞事件，省得打开日历应用了。
批量发送场景也常见。比如运维需要给整个部门发维护通知，我会写个 for 循环读用户列表：`for user in $(cat users.txt); do lark message send --receiver=$user --msg_type=post --content_file=notice.json; done`。content_file 那块我踩过雷——你传 JSON 得注意格式，比如 post 消息的 content 必须包含 title 和 content 字段，否则会静默失败。我的习惯是先手动发一条看看返回的 JSON 结构，照葫芦画瓢。
配置文件和调试技巧
上手一段时间后我发现，光靠环境变量和命令行参数不够灵活。飞书 CLI 支持一个 YAML 配置文件，默认路径是 ~/.lark/config.yaml。我习惯在里面写好默认的 App ID、Secret 和日志级别，这样每次敲命令就不用带一堆参数。比如：
app_id: "cli_xxxxxxxx"
app_secret: "xxxxxxxxxxxxxxxxx"
log_level: "info"
timeout: 30
日志级别那里特别有用。平时 debug 的时候设为 debug，能看 CLI 实际发了啥 HTTP 请求和响应体。我遇到几次发送失败但没报错的情况，把这个调成 debug 后才发现返回值里提示权限不足。timeout 默认好像是 10 秒，但我遇到过飞书 API 偶尔慢的情况，设到 30 秒更稳妥。另外配置里还可以指定默认的 receiver，比如 `default_receiver: "ou_xxxxxxxx"`，这样测试时临时改个文本内容就能快速发给自己。
调试还有个土办法——把命令加个 `--dry-run` 参数。有些 CL I工具会模拟执行但不真发请求，飞书 CLI 也有类似的。我用这个校验参数拼得对不对，比如看看 receiver 的 ID 是不是有效的。更彻底的方式是用 `--output=json` 把返回结果变成 JSON 格式，然后传给 jq 工具解析。比如 `lark user search --email=xxx@company.com --output=json | jq '.data.user_id'` 直接拿到用户 ID，省得去字符串里扒拉。
常见报错和解决办法
用飞书 CLI 这么久，我碰到的报错五花八门，但最频繁的就那几种。首先是 token 过期，报错成“invalid access token”。我一开始傻傻地去生成新的 App Secret，后来发现只要重新跑一次认证命令就行。不过如果你用的 OAuth 方式而不是 App 内建 token，那 token 确实有时效性，得刷新。我的解决方式是写个 cron 每小时跑一次 `lark auth refresh`，这样自动化任务不会半夜断掉。
第二个常见问题是权限不足。明明 App 配置了权限范围，但 CLI 报“permission denied”。这通常是你创建应用时没把要用到的权限点上，比如要发消息就要勾选“发送消息”权限，要读文档就要勾“查看文档”。而且注意有些权限需要审核通过才生效，光点选没用。有一次我给 App 加了“多维表格”权限，等了两小时才生效，期间一直 403。我现在的习惯是在开放平台先测试权限，确认接口能用再回 CLI。
第三个是网络问题。飞书 API 在国内直连没问题，但如果你在海外或者某些限制网络的环境，超时或 SSL 证书报错很常见。我遇到过 `x509: certificate signed by unknown authority`，查半天发现是公司内网防火墙劫持了 HTTPS。解决方式要么配代理：`export HTTP_PROXY=http://proxy.company.com:8080`，要么在 CLI 的命令上加 `--insecure` 跳过证书验证，但生产环境我不建议这么干。其实最稳的办法是在飞书开放平台把域名加入白名单，或者跟 IT 申请出站规则。
结合 CI/CD 和自动化流程
我真正觉得飞书 CLI 牛逼的地方是跟各种自动化工具联用。比如在 GitHub Actions 里面，每次代码 push 后跑完测试，如果失败了就发个消息到组里。我在 .github/workflows/ci.yml 里加上一个步骤：
steps:
- name: notify on failure
if: failure()
run: lark message send --receiver=chat_xxxx --msg_type=post --content='{"title":"构建失败","content":"[[测试未通过，日志见附件]]"}'
注意这里 content 是 post 格式的 JSON，在 shell 里用单引号包住。但你要是在 Windows 上跑，得处理引号转义。我后来改用环境变量把内容塞进去，比如 `CONTENT=$(cat fail_notice.json)`，然后用--content 直接传变量，避免引号打架。
Jenkins 上也是类似的思路，把你的飞书 CLI 安装在 Jenkins 节点上，在 Pipeline 里调 `sh 'lark message send ...'`。我曾想过把多维表格更新也集成进去——每次部署完成，执行 `lark sheet append --spreadsheet_token=xxxx --values="[\"2024-01-15\", \"成功\", \"v2.3.1\"]"` 自动将记录写到表格里。这个操作用惯了你就不想再手动维护什么部署日志了。
需要注意的坑是：CI 环境里别直接把 App Secret 写死在代码里。我习惯在 GitHub 用 Secrets 存，在 Jenkins 用 Credentials Binding 加载。另外一些 CI 容器可能没装飞书 CLI，得在构建的第一步先跑安装脚本，或者干脆把 CLI 做成 Docker 镜像的一部分。我之前踩过：用了一个很新的 Alpine 基础镜像，结果飞书 CLI 的二进制依赖 glibc 跑不起来，换成 Ubuntu 才算完。
个人总结和避开的小弯路
飞书 CLI 不是什么黑科技，但它确实把飞书从一个“聊天软件”变成了一个“可编程的办公基础设施”。我最喜欢的是它的文档导出功能，以前我得手动把飞书文档贴到 Markdown 里，又慢又容易丢格式。现在一条命令搞定，甚至能配合 sed 做批量替换，直接生成公司 wiki 的源头。另一个实用场景是批量拉取员工信息，做组织架构图或者周期性报表，用 CLI 加一行 awk 就能筛出你需要的数据。
不过也要承认它的局限性。CLI 毕竟不是全图形化的，对不熟悉终端的人来说初次配置有点门槛。我建议新手先不要直接上手复杂的自动化，而是从发一条消息开始，慢慢熟悉命令和参数格式。还有，官方的 CLI 文档其实不算特别详细，有些参数说明得靠猜。我每次遇到生僻命令都会先跑 `lark [子命令] --help` 看帮助信息，比翻网页快得多。
如果让我给你一个最实在的建议：在配置好之后，给自己写个小 shell 脚本或 alias，比如 `alias sendme='lark message send --receiver=ou_xxx --msg_type=text'`，这样日常想给自己发条提醒时直接 `sendme "记得打卡"`，比掏出手机开 App 快十倍。这种顺手把 CLI 揉进日常的习惯，才是它真正的价值所在。