飞书命令行工具cli到底怎么玩，折腾了一下午总算搞懂了

下载飞书cli前，你得先搞清楚这是个啥

说实话，我第一次看到飞书cli这东西的时候，完全懵了。我记得那天下午，我正琢磨着怎么把一些重复性的飞书操作自动化，比如批量发消息、批量拉人进群之类的手动操作太费时间了。然后听群里有人提了一嘴飞书命令行工具，我一搜飞书下载，出来一堆链接，点进去一看，什么飞书桌面版、移动版都有，就是没找到那个cli的影子。后来我才发现，飞书cli其实是个单独的项目，不跟普通飞书客户端混在一起，你得专门去开发者文档那块找。

折腾半天，我总算理解了，这个cli本质上就是个基于飞书开放平台API的命令行工具包，你装完以后，直接在终端里敲命令就能操作飞书的各种功能。比如你想给某个用户发一条消息，不用打开飞书界面，只需要一条命令搞定。听起来高大上，但刚开始配置的时候差点让我放弃。

下载与安装步骤，其实没那么复杂但坑不少

当你找到正确的下载入口后，点本页下载按钮，会拿到一个压缩包。我当时手快，直接解压找了个地方就放着了，结果后面各种报错。正确的做法是，你得先看看你的操作系统，飞书cli支持Windows、macOS和Linux，但每个系统的安装方式都不一样。我用的macOS，解压后是一个可执行文件，得把它扔到系统PATH里才能全局调用。网上有教程说直接拖到/usr/local/bin就行，但我的系统报权限错误，后来加了个sudo才搞定。

Windows那边我也试过，双击exe文件没反应，我当时还以为下载包坏了。后来发现其实cmd命令窗口里才能运行，先进到解压目录，再输入文件名加上参数。Linux用户倒是省心，直接chmod加执行权限就能用。不过有个坑，不管哪个系统，第一次运行都会提示你配置token，这一步跨不过去。我当时卡在这里半小时，因为文档说可以去飞书开放平台申请，但申请完填进去还是报错，后来才意识到令牌分好几种，cli要的是bot的token，不是企业自建应用的。

配置环境变量和token，这一步最磨人

装完cli你以为就能用了？天真。我第一次敲了个飞书cli help，蹦出一堆命令列表，心里正高兴呢，结果试了个发消息的命令，直接返回授权失败。问题就出在环境配置上。你得先设几个环境变量，具体来说就是FEISHU_APP_ID、FEISHU_APP_SECRET这些，不然cli不知道你是谁家的bot。

我试过直接在终端里export，但换个窗口就失效了，后来老老实实写进.bashrc或者.zshrc文件里。还有个细节，有些版本的cli要求token以文件形式存放，你得在用户目录下建个.flybook这样的隐藏文件夹，把配置文件扔进去。我当时看网上教程，有人说要建，有人说不用，我两种都试了，最后发现最新版本其实支持直接用环境变量传参，只不过命令格式不一样。

有个小技巧，配置完后先跑一遍飞书cli version，如果能正常显示版本号，说明环境配通了。如果还是报错，大概率是token过期了。飞书的token有效期一般就两个小时，所以后来我写了个小脚本，每天早上自动刷新一下token再跑批量任务，省得手动操作。

基础命令的使用场景，从发消息到查成员

飞书cli最实用的功能我觉得就是发消息。比如你要给一个群发个定时提醒，传统做法是在飞书里设机器人，但机器人只能回消息，不能主动发。用cli的话，一行命令就能解决：飞书cli message send --receiver 群ID --text "大家记得打卡"。我第一次试的时候，死活找不到群ID去哪看，后来发现要到飞书网页版的管理后台，点群设置那里找个以oc_开头的字符串。

还有个查询成员的场景，我经常用飞书cli user list这个命令拉出全公司的员工列表，配合grep能快速找到某个人的邮箱或手机号。以前我都是手动翻通讯录，翻得眼都花了。不过有个坑，这个命令默认只返回前100条记录，公司人多的话得加个--page-size参数，比如设置成500，不然数据不全。我一开始没注意，拉了几次数据都不对，还以为代码写错了。

参数这块，大部分命令都支持--format json，这对我这种喜欢处理结构化数据的人来说太爽了。比如你发消息时加个--format json，返回的结果里就有消息ID、发送状态这些字段，方便后面做日志记录或者重试操作。我后来把所有自动化任务都改成了json输出，配合jq命令解析，比看那些杂乱的纯文本舒服多了。

踩过的那些坑，权限和超时问题最常见

权限问题是我栽得最多的坑。第一次想用cli创建一个群，明明命令写对了，返回却是权限不足。后来查文档发现，飞书cli的bot默认只有发消息和查看成员这两种权限，像创建群、修改群设置这种高级操作，需要在飞书开放平台的应用权限管理里单独申请。而且申请完还得等审核，我那次等了两个小时才审核通过，中间试了十几次，全是403。

超时问题也挺无语的。有一次我写了个批量拉用户的脚本，循环调用飞书cli user get命令，结果跑到一半卡住了。最后发现是因为短时间内请求太频繁，触发了飞书API的限流。官方文档写的是每个请求间隔不能小于100毫秒，但我实际测下来，500毫秒都不一定稳。后来我在循环里加了sleep 1，才总算跑通了。

还有个很隐蔽的问题，就是飞书cli本身更新频率不低。我刚装好时候是1.2版本，过了一个月它出了1.3，结果我原来的命令有些废弃了，跑起来直接报deprecated警告。所以建议你隔段时间点本页下载按钮看看有没有新版本，或者直接加个自动更新检测脚本。我有次就因为版本旧，导致一个自动化任务跑错了一整天，事后复盘才发现是命令参数变了。

批量任务脚本怎么写，我的实践心得

学会了基础命令和参数后，我开始尝试写脚本自动化一些重复操作。比如每天早上8点，我要给十几个项目群发日报提醒。手动发太累，我就写了个shell脚本，用一个数组存好所有群ID，然后循环调用飞书cli message send。核心逻辑很简单，但要注意群ID的格式验证，因为飞书的群ID有oc_、corp_等多种前缀，如果不统一处理，粘贴时会漏掉某个群。

参数设置上，我一般会加个--title字段设置消息标题，这样发出来的消息在飞书里会显示成卡片样式，比纯文本正式多了。还有--at-all这个参数，但慎用，因为全体艾特会打扰所有人，我一般只在紧急通知时用。有一次我用错了参数，把全体艾特用在了日常提醒上，结果我的bot被群成员投诉了好几个。

脚本里还有一个很实用的技巧，就是结合飞书cli的--dry-run参数。加了这个参数后，命令只会模拟执行，不会真的发送消息，可以用来测试脚本逻辑对不对。我每次改完脚本，都会先跑一遍--dry-run，确认群ID、消息内容都没问题，再去掉这个参数正式运行。这个习惯救过我很多次，有一次群ID拼错了，要不是dry-run先检测出来，可能就把消息发到无关群去了。

实际工作中的应用案例，从个人到团队推广

我真正体会到飞书cli的威力，是在一次给某部门做批量新人培训通知的时候。运营部门要把50个新入职的员工拉进一个专门的学习群，然后发欢迎消息和课程链接。以前靠人工操作，一个人拉入群要花至少两分钟，50个人就是将近两小时，还得小心别拉错人。我用cli写了个脚本，先调用飞书cli user list从HR系统导出的Excel里拿到所有新人邮箱，再用循环配合add group成员命令，一小时内全搞定了，而且零错误。

后来我又把这套方案推广到了我们团队，教他们怎么用飞书cli搞自动化。有个同事一开始完全不想学，觉得命令行太硬核，我就写了个简单的交互式菜单，比如显示请输入操作编号: 1.发消息 2.查成员 3.拉群，然后脚本后台调用cli命令。这人用了一次就真香了，现在他自己都会改脚本参数了。

不过说实话，飞书cli也有局限性。比如它缺少直观的图形界面，偶尔出个错误日志，你得一行一行看，不像飞书客户端那样可以点按钮排查。而且对于不熟悉终端操作的人，初次配置的门槛确实高。我建议新手先别急着做复杂脚本，就从小范围功能开始，比如每天用飞书cli给自己发个待办提醒，等熟悉了命令结构和参数含义再逐步扩大使用范围，这样不会一开始就被劝退。