飞书 CLI 安装使用完整指南：命令行操作日历/文档/消息，AI Agent 接入实测（2026）
飞书 CLI（@larksuite/cli，命令名 lark-cli）是字节官方推出的命令行工具，一条命令安装：npx @larksuite/cli@latest install，三步完成登录（config init → auth login --recommend → 验证）。它覆盖 18 个业务域、200+ 命令——日历、消息、文档、多维表格、审批、OKR 全部能在终端里操作，还内置 26 个 AI Agent Skills，让 Claude Code、Cursor、Codex 直接替你操作飞书。本文从安装、登录、核心命令到 AI 接入完整走一遍，最后说说它真正的价值点（提示：不在人类用户身上）。
我是被一篇"Codex 直接在飞书文档里画泳道图"的帖子种草的。当时的第一反应和你一样：飞书是个 GUI 产品，要 CLI 干什么？装完用了一周，我改变了看法——这个工具的目标用户根本不是人，是 AI Agent。官方 README 里写得很直白：面向 “humans and AI Agents”，而且排在后面的那个才是重点。理解了这一点，这个工具的所有设计就都说得通了。
飞书 CLI 是什么？先看它能干什么
lark-cli 是飞书开放平台的官方 CLI（npm 包 @larksuite/cli，MIT 协议，字节官方维护，当前版本 1.0.67）。能力范围一句话：飞书里你手点能干的事，它基本都有对应命令。
覆盖的业务域（共 18 个）：
三个设计细节说明它的"Agent-Native"定位：输入注入防护（防提示注入攻击）、凭据存进系统钥匙串（不是明文配置文件）、JSON 输出严格分流（成功走 stdout、错误走 stderr——这是给程序读的，不是给人看的）。
安装：一条命令，30 秒搞定
前置要求只有 Node.js（有 npx 即可）。
方式一：npm 安装（推荐）
npx @larksuite/cli@latest install
方式二：源码安装（需要 Go 1.23+ 和 Python 3，普通用户不需要走这条路）
git clone https://github.com/larksuite/cli.git
cd cli
make install
npx skills add larksuite/cli -y -g # 源码方式需手动装 AI Skills
方式三：懒人方式——把安装命令直接丢给你的 AI 工具。飞书官方文档自己都这么建议：把指令复制发给 TRAE、Cursor、Codex 或 Claude Code，让它替你完成安装。实测 Claude Code 能全程自助搞定，包括踩到 npm 权限问题时自己换目录重试。
登录授权：三步走 + 一个关键概念
# 第 1 步：初始化配置
lark-cli config init
# 第 2 步：登录授权（--recommend 自动申请常用权限集）
lark-cli auth login --recommend
# 第 3 步：验证——拉今天的日程试试
lark-cli calendar +agenda
第 2 步会打开浏览器走 OAuth 授权，扫码确认即可。关键概念是 scope（权限范围）：--recommend 申请的是推荐权限集，够日常用；要精细控制可以按域授权：
lark-cli auth login --domain calendar,task # 只授权日历和任务
lark-cli auth login --scope "calendar:calendar:read" # 精确到单个权限点
配套命令一览：auth status（查登录态）、auth scopes(查已授权限)、auth logout（登出）。无浏览器的服务器环境用 --no-wait + --device-code 设备码流程。
编者注： 很多人卡在"装完就想跑命令"，跳过了 config init——它负责生成本地配置和钥匙串条目，跳过会报找不到凭据。另一个常见坑是换飞书账号：直接重新 login 可能残留旧缓存，干净的做法是先 auth logout 再登，还不行就卸载重装清缓存（社区已有专门讲这个问题的帖子，说明踩的人不少）。
核心用法：三层命令体系，从人类友好到全量 API
lark-cli 的命令分三层，理解这个结构就掌握了整个工具：
第 ① 层：Shortcuts（+ 前缀）——人类和 AI 都爱用
# 看今日日程
lark-cli calendar +agenda
# 发消息到群
lark-cli im +messages-send --chat-id "oc_xxx" --text "Hello"
# 用 Markdown 直接建文档
lark-cli docs +create --doc-format markdown --content $'<title>Weekly Report</title>\n# Progress\n- Completed feature X'
第 ② 层：API Commands——与开放平台端点 1:1 映射（100+ 命令）
lark-cli calendar calendars list
lark-cli calendar events instance_view --params '{"calendar_id":"primary","start_time":"1700000000","end_time":"1700086400"}'
第 ③ 层：Raw API——直接打 2500+ 个开放平台接口
lark-cli api GET /open-apis/calendar/v4/calendars
lark-cli api POST /open-apis/im/v1/messages --params '{"receive_id_type":"chat_id"}' --data '{"receive_id":"oc_xxx","msg_type":"text","content":"{\"text\":\"Hello\"}"}'
四个高频实用参数：
● --format json/pretty/table/ndjson/csv——输出格式，写脚本用 json，人看用 table
● --page-all——自动翻完所有分页（拉全量数据必备）
● --dry-run——预演不执行，发消息前先看看会发出什么
● --as user / --as bot——身份切换，同一条命令可以以你的身份或机器人身份执行
--dry-run 值得特别表扬：让 AI Agent 替你发消息之前先预演一遍，这是防"AI 幻觉发错群"的保命参数。
重头戏：接入 Claude Code / Cursor / Codex
这才是 lark-cli 的真正价值。它没走 MCP 路线，而是用 Skills 机制——内置 26 个 Agent Skills（lark-calendar、lark-im、lark-doc、lark-base、lark-mail 等），npm 安装时自动写入本机 Agent 工具的 skill 目录，Claude Code / Cursor / Codex 无需任何额外配置，装完就能用。
AI Agent 场景的四步快速开始：
npx @larksuite/cli@latest install
lark-cli config init --new
lark-cli auth login --recommend # 授权 URL 会转给你，人工扫码确认
lark-cli auth status
之后你就可以对 Claude Code 说人话了：
● “把这份周报整理成飞书文档发到项目群”
● “查我明天的日程，有冲突的话给对方发消息改期”
● “把这个 CSV 导入多维表格并建一个按状态分组的视图”
实测体验：文档和日历操作成功率很高；多维表格的复杂操作（跨表关联、工作流）偶尔需要人工补一步。整体上，"AI 操作飞书"从需要自己写开放平台对接代码，变成了装一个 CLI 的事——这是质变。
安全提醒（官方 README 原文强调，我原样转达）： 授权后 Agent 是以你的身份操作飞书的。存在模型幻觉、提示注入风险。官方建议：不要修改默认安全设置、机器人只当私人助手用、不要把它加进群聊。我再加一条实践建议：给 Agent 用的授权尽量用 --domain 收窄范围，别图省事全量授权。
说句实话：谁该装，谁不该装
用了一周，我的判断很明确：
不该装的：指望用 CLI 替代飞书客户端日常办公的人。终端里发消息不会比点鼠标快，+agenda 看日程也不会比手机瞄一眼快。作为"人类工具"，它的效率提升接近于零。
该装的：① 用 Claude Code/Cursor/Codex 的开发者——这是目前把 AI Agent 接入国内办公系统最低成本的方案，没有之一；② 需要批量操作的人——比如把 200 条记录导入多维表格、批量下载群文件，--page-all + csv 输出一条命令的事；③ 写自动化脚本的——比 SDK 对接开放平台省 80% 的代码。
一句话总结：它是"给 AI 用的飞书键盘"，人类只负责装好和授权。
FAQ：飞书 CLI 高频问题
Q：飞书 CLI 是官方的吗？安全性如何？
是。npm 包 @larksuite/cli 由字节官方维护（maintainer 是 bytednpm），MIT 开源，代码在 GitHub larksuite/cli。凭据存系统钥匙串而非明文文件，带输入注入防护。真正的安全变量不是工具本身，而是你授权给 AI Agent 的权限范围——用 --domain 收窄它。
Q：支持哪些系统？
macOS / Linux / Windows 都支持，只要有 Node.js 环境。服务器无浏览器环境用设备码授权（--device-code）。
Q：和飞书开放平台 SDK 什么关系？
CLI 底层就是开放平台 API（第三层 Raw API 直接映射 2500+ 接口）。区别在使用成本：SDK 要写代码建应用，CLI 装完授权就能跑。轻量自动化和 AI Agent 场景用 CLI，正式应用开发用 SDK。
Q：换账号登录出问题怎么办？
先 lark-cli auth logout 再重新 login；仍有残留就卸载全局 npm 包重装，清掉本地缓存后重新授权新账号。
总结
飞书 CLI 的安装使用可以压缩成四行命令：npx @larksuite/cli@latest install → lark-cli config init → lark-cli auth login --recommend → lark-cli calendar +agenda 验证。它对人类用户是个"还行"的工具，对 AI Agent 用户是个"必装"的工具——26 个内置 Skills 让 Claude Code、Cursor、Codex 零配置获得操作飞书全家桶的能力。如果你的办公流在飞书、开发流在 AI Coding 工具，这是 2026 年连接两者最短的那条线。
本文基于 @larksuite/cli v1.0.67 与官方 GitHub README 实测整理（2026 年 7 月），命令与权限机制以官方文档最新版为准。
