飞书CLI到底是个啥？试了才知道多省事

飞书CLI到底是个啥？试了才知道多省事

以前在飞书上管项目、写机器人，总得开着浏览器，点来点去，发布个版本还得等页面加载半天。后来同事跟我说，飞书有个CLI工具，能直接在终端里操作，我第一反应是这玩意儿能有多好用？不就是个命令行黑框框嘛。结果试了一次就回不去了——尤其是当你一天要发布十几个版本、或者批量改权限的时候，敲几下键盘比点鼠标快十倍，而且不会因为浏览器卡顿而抓狂。

飞书CLI的全称是Feishu CLI，官方叫它「飞书开发者工具」，本质上是个装在电脑上的命令行程序。它能让你用命令来操作飞书开放平台上的应用、机器人、云文档、审批流等等。你不需要登录网页后台，不用反复找菜单，一条命令下去，任务就自动跑了。比如你写了个机器人应用，以前改完代码，得手动上传压缩包、填写版本说明、点击发布，现在一个`feishu app deploy`就搞定。如果你是开发者，或者经常需要跟飞书的应用配置打交道，这工具绝对算是省事利器。

下载飞书CLI的正确姿势，别踩坑

我第一次下载飞书CLI的时候，在网上搜了半天，信息乱七八糟。官方的文档藏得有点深，在飞书开放平台的开发者后台里，要找到「开发者工具」那一栏才看得到下载入口。其实最直接的办法，是去飞书开放平台的官网，点那个「开发者工具」的导航，里面就有飞书CLI的下载页。不推荐去第三方网站下，版本不对或者夹带私货就麻烦了。

点本页下载按钮，你会看到支持Windows、macOS和Linux三种系统的安装包。我用的Mac，选的是dmg格式，下载后双击挂载，把应用拖进「应用程序」文件夹就完事。Windows用户是exe安装包，一路下一步就行。Linux用户需要手动解压一个tar.gz包，把二进制文件放到`/usr/local/bin`里。装完之后，打开终端敲`feishu -v`，如果能看到版本号，就说明装成功了。第一次装的时候，我忘了加环境变量，结果敲命令报错「command not found」，急得我差点重装——后来才发现Mac的dmg安装其实会自动配置路径，但如果你解压了tar包放着没挪位置，就得自己配PATH。

初次配置：搞定Token和权限

装完工具还不算完，得先跟你的飞书账号绑定。启动一个新终端，输入`feishu login`，它会弹出一个浏览器窗口让你扫码登录。这个扫码用的是飞书开放平台的应用权限，跟你平常聊天的飞书账号不太一样——你得先在开发者后台创建一个应用，拿到App ID和App Secret，然后在命令行里配置。我第一次搞这步时，把应用权限范围设错了，导致后面发消息时老是报「权限不足」，后来才发现是要在应用权限管理里勾选「获取用户信息」和「发送消息」这两个scope。

登录成功后，命令行会提示“Login successful”，并自动保存一个token在你的用户目录下，有效期一般是24小时。如果你长时间不用，token过期了，再跑命令就会报401错误，这时候重新执行`feishu login`补一下就行。我个人习惯在每天早上开工前先跑一遍这个命令，省得干到一半被卡住。另外，如果用的是企业内部自建应用，你可能还需要配置一个`feishu init`来设置app_id和app_secret，这些信息在开发者后台的应用「凭证与基础信息」页里，复制粘贴进去就行。

日常命令：从看状态到发消息

搞定配置后，我第一个试的是`feishu app list`，这命令能在终端里列出你所有在飞书开放平台创建的应用，包括应用名称、状态、更新时间。以前我想看应用是不是处于「已审核通过」状态，得登录后台翻半天，现在秒出结果。另一个常用的命令是`feishu app info --app-id=xxx`，它能显示一个应用的详细配置，比如应用名称、描述、权限列表，甚至还能看到当前的版本号。

我最喜欢的功能是群聊消息发送。`feishu message send --receive_id=xxxx --msg_type=text --content="你好，这是一条来自CLI的测试消息"`，这条命令能直接往指定用户或群聊里发文本消息。注意receive_id是open_id，不是你的微信号——你得先通过`feishu user search`命令找到那个人的open_id。第一次用的时候，我发消息给自己，结果对方没收到，检查了半天才发现receive_id填错了。后来写脚本时，我会先用`feishu user info --mobile=手机号`拿到正确的id，再放进消息命令里，百试不爽。

管理应用版本和发布，效率翻倍

开发飞书应用时，最烦的就是版本管理。网页后台的发布流程分好几步：先新建一个版本，上传代码包，填版本描述，提交审核，再等审核通过后手动发布。用CLI就简单多了。`feishu app version create --app-id=xxx --version=1.0.1 --desc="修复了某某bug"`，这命令直接创建一个新版本，无需拖拽上传。然后`feishu app version describe --app-id=xxx --version=1.0.1`可以查看审核状态。

正式发布用`feishu app version publish --app-id=xxx --version=1.0.1`，如果应用之前已经审核通过，这条命令能一键上线，省掉在浏览器里点那个「发布」按钮的步骤。我有次赶着修复线上bug，连续发布了三个版本，网页后台卡得我血压飙升；换成CLI后，一个shell脚本搞定全部操作，10秒内三个版本全部上线，当天提前下班。注意这里的版本号格式必须是x.y.z，而且不能跟已有版本重复，否则会报错“version already exists”。

踩坑实录：权限、网络和编码问题

说实话，飞书CLI不是没有坑。第一个常见问题是网络不通。如果你的公司网络用了代理，CLI可能连不上飞书的API，报错信息是`net/http: TLS handshake timeout`。我在公司遇到过，解决方法是在终端里设置`http_proxy`和`https_proxy`环境变量，让CLI走代理。或者更直接点，在家里的网络下操作，飞书服务器在国内，速度挺快的。

第二个坑是权限冲突。如果你同时在开发者后台和CLI里操作同一个应用，CLI推送的修改可能会被后台的保存操作覆盖掉。我的习惯是，大修改用后台，小修改和发布全用CLI，避免两边不同步。另外，文件编码问题也遇到过——上传代码包时，如果压缩包里包含中文文件名或者非UTF-8编码的文本，飞书CLI会报“invalid file format”的错误。解决办法很简单：确保所有代码文件都是UTF-8编码，压缩包用zip格式，别用rar或者7z。有一次我忘了解压直接上传了源文件夹的tar包，结果半天没成功，同事提醒才知道命令行默认只认zip。

写在最后：谁应该用飞书CLI

飞书CLI不是给所有人用的。如果你只是偶尔在飞书上发个消息、开个审批，那网页够用了。但如果你是深度开发者，每天要跟飞书应用、机器人、云文档打交道，那这工具绝对是效率神器。尤其是配合CI/CD流水线，你可以在代码提交后自动运行`feishu app deploy`，实现从代码到发布的全自动化。我自己的一个机器人项目，就靠这套流程，每次github push后，自动压缩代码、更新版本、发布上线，全程不用人盯着。

最后给个实用建议：飞书CLI帮助文档通过`feishu help`就能看到所有命令列表，新手先跑一遍`feishu app list`和`feishu user search`这两条命令，感受一下终端的反馈速度，绝对比你想象中靠谱。当然，要是碰上版本更新或者bug，飞书官方GitHub上有个issues页面，很多问题别人早就踩过并解决了，搜一搜比到处问人快得多。