LarkSuite/cli · 上手攻略

• 仓库：LarkSuite/cli
• 链接：https://github.com/larksuite/cli
• 分类：开发者工具 / 企业协作 / AI Agent
• 作者：Tom
• 更新：2026-08-06

这是什么

larksuite/cli（又称 lark-cli）是飞书（Lark/Feishu）官方维护的 CLI 工具，让人类和 AI Agent 都能在终端里操作飞书生态。覆盖消息、云文档、多维表格、电子表格、幻灯片、日历、邮箱、任务、会议、审批、OKR 等 18 大业务域，提供 200+ 精选命令和 26 个 AI Agent Skills，MIT 协议开源。

它的核心设计哲学是三层调用架构：

快捷命令（+前缀） → API 命令 → 通用调用（Raw API）

人类用 + 前缀的快捷命令（如 lark-cli im +messages-send），AI Agent 用底层 API 命令或 Raw API，三层无缝切换。

解决什么问题

飞书开放平台（Open Platform）有 2500+ 个 API 端点，直接调用门槛高、参数复杂、Agent 容易失败。larksuite/cli 做了三层封装：

1. 快捷命令层（+ 前缀）：人类友好，有智能默认值、表格输出、dry-run 预览
2. API 命令层：与飞书平台元数据严格同步，100+ 精选命令对应平台核心端点
3. 通用调用层（api 子命令）：直接访问任意 Raw API，覆盖全部 2500+ 端点

对于 AI Agent，它还内置 26 个结构化 Skills（覆盖日历、消息、文档、表格、审批等），让 Agent 可以用自然语言驱动飞书操作，无需手动拼装 API 参数。

快速安装

环境要求

• Node.js（npm/npx）
• （源码构建额外需要：Go v1.23+ 和 Python 3）

安装步骤

# 方式一：从 npm 安装（推荐）
npx @larksuite/cli@latest install

# 方式二：从源码安装
git clone https://github.com/larksuite/cli.git
cd cli
make install

初始化配置

# 安装 CLI Skill（必需，用于 AI Agent 识别）
npx skills add larksuite/cli -y -g

# 配置应用凭证（交互式引导，只需一次）
lark-cli config init

# 登录授权（--recommend 自动选择常用权限）
lark-cli auth login --recommend

# 验证登录状态
lark-cli auth status

AI Agent 快速开始

# 第 1 步：安装
npx @larksuite/cli@latest install

# 第 2 步：配置（后台运行，输出授权 URL，发给用户完成浏览器授权）
lark-cli config init --new

# 第 3 步：登录（同样后台运行，提取授权 URL）
lark-cli auth login --recommend

# 第 4 步：验证
lark-cli auth status

核心用法

快捷命令示例（+ 前缀）

# 查看日历议程
lark-cli calendar +agenda

# 发送即时消息
lark-cli im +messages-send --chat-id "oc_xxxxx" --text "Hello"

# 创建 Markdown 文档
lark-cli docs +create --doc-format markdown --content $'<title>周报</title>\n# 本周进展\n- 完成 X 功能'

# 以机器人身份发送消息
lark-cli im +messages-send --as bot --chat-id "oc_xxxxx" --text "Bot message"

API 命令示例

# 列出日历列表
lark-cli calendar calendars list

# 获取指定事件详情
lark-cli calendar events instance_view \
  --params '{"calendar_id":"primary","start_time":"1700000000","end_time":"1700086400"}'

Raw API 调用

# GET 请求
lark-cli api GET /open-apis/calendar/v4/calendars

# POST 请求（带 body）
lark-cli api POST /open-apis/im/v1/messages \
  --params '{"receive_id_type":"chat_id"}' \
  --data '{"receive_id":"oc_xxxxx","msg_type":"text","content":"{\"text\":\"Hello\"}"}'

输出格式控制

--format json    # 完整 JSON（默认）
--format pretty  # 人性化格式
--format table   # 表格
--format ndjson  # 换行分隔 JSON（适合管道）
--format csv     # CSV

自动翻页

--page-all       # 自动翻页获取全部数据
--page-limit 5   # 最多 5 页
--page-delay 500 # 每页间隔 500ms

预览（dry-run）

lark-cli im +messages-send --chat-id oc_xxxxx --text "hello" --dry-run

Schema 查看

# 查看所有 API schema
lark-cli schema

# 查看指定方法参数
lark-cli schema calendar.events.instance_view
lark-cli schema im.messages.delete

26 个 AI Agent Skills 速览

典型适用场景

1. AI Agent 自动化工作流：让 AI Agent 自动发送飞书消息、创建日历、查询任务，无需手动操作
2. 日常运维脚本化：将飞书通知、文档创建等重复操作写成脚本，纳入 CI/CD 流程
3. 数据导出与迁移：批量导出飞书表格/文档数据，用于备份或第三方分析
4. 审批自动化：定时检查待审批事项并自动处理（需注意安全警告）
5. 团队日报/周报机器人：结合 cron 定时任务，自动收集并汇总团队进展

坑与注意

1. 安全风险（重要）：README 明确警告——不要将机器人拉入群聊或允许其他用户与其交互，以免权限被滥用；建议仅作为私人对话助手使用
2. 成功判断标准：ok == true（或进程退出码 0）表示成功，不要用 code == 0 判断——Raw API 错误时 code 在 error 对象内
3. Node.js 必需：npm 安装方式依赖 Node.js 运行时，Go 源码编译也需要 Node.js 做技能初始化
4. 认证需要浏览器配合：AI Agent 安装模式下，config init --new 和 auth login 需要用户在浏览器完成授权，不是完全无人值守
5. 风控信号：CLI 默认向飞书官方域名发送 OS 类型和设备型号用于安全风控，可用 lark-cli config risk-control off 关闭（存在安全风险）
6. 权限粒度：--recommend 自动选常用权限，但涉及敏感操作（如审批、邮件）可能需要手动指定更细粒度的 scope

与同类对比

larksuite/cli 的核心优势是三层封装 + AI Agent 原生，不需要写一行 Python/Go 代码就能在终端里操作飞书，且对 AI Agent 友好。如果你只需要操作飞书，而不关心底层实现，这是最快的方式。

一句话推荐结论

飞书生态的终极 CLI 瑞士军刀——无论你是人类开发者还是 AI Agent，安装后三分钟就能开始操作飞书的所有核心业务域，比任何 SDK 都快，比任何网页操作都可脚本化。

原始仓库：https://github.com/larksuite/cli（MIT License）