Lark / Feishu CLI

lark-cli

中文版 | English

官方 Lark/Feishu 命令行工具，由 larksuite 团队维护，专为人类和 AI Agent 打造。覆盖 Messenger、Docs、Base、Sheets、Slides、Calendar、Mail、Tasks、Meetings、Markdown 等核心业务领域，提供 200 多条命令和 26 个 AI Agent Skills。

安装 · AI Agent Skills · 认证 · 命令 · 高级用法 · 个人或企业 · 安全 · 参与贡献

为什么选择 lark-cli？

• 原生适配 Agent — 内置 24 个结构化 Skills，兼容主流 AI 工具，Agent 无需额外配置即可操作 Lark
• 覆盖广泛 — 涵盖 18 个业务领域、200 多条精选命令和 26 个 AI Agent Skills
• 对 AI 友好且经过优化 — 每条命令都经过真实 Agent 测试，参数简洁、默认值智能、输出结构化，最大限度提高 Agent 调用成功率
• 开源，零门槛 — 采用 MIT 许可证，开箱即用，只需执行 npm install
• 3 分钟即可上手 — 一键创建应用、交互式登录，从安装到首次 API 调用只需 3 步
• 安全且可控 — 防止输入注入、清理终端输出，并使用操作系统原生密钥链存储凭据
• 三层架构 — 快捷命令（便于人类和 AI 使用）→ API 命令（与平台同步）→ 原始 API（全面覆盖），可选择合适的粒度

个人还是企业？

你是……	推荐路径
个人开发者 — 在终端中或配合自己的 AI Agent 使用 lark-cli	按照下方的快速入门操作
企业 IT / ISV — 将 lark-cli 集成到自己的 Agent 或平台中，集中管理凭据（数据库 / Vault / 配置中心）、统一审计日志并限制可用命令	阅读将 lark-cli 集成到你的 Agent和 extension/ 软件包；通过包装器 main 扩展，无需修改 CLI 源码

💡 致 AI Agent： 在任意开放平台文档 URL 后附加 .md，即可获取原始 Markdown，例如 embed-feishu-cli-in-agent.md。

功能

类别	功能
📅 日历	查看、创建和更新事件，邀请参与者，查找会议室，回复邀请，查看空闲/忙碌状态和时间建议
💬 Messenger	发送/回复消息，创建和管理群聊，查看聊天记录和讨论串，搜索消息，下载媒体
📄 文档	创建、读取、更新和搜索文档，读取/写入媒体和白板
📁 云盘	上传和下载文件，搜索文档和知识库，管理评论
📝 Markdown	创建、获取、修补和覆盖云盘原生 .md 文件
📊 多维表格	创建和管理表格、字段、记录、视图、仪表盘、工作流、表单、角色和权限，以及数据汇总和分析
📈 Sheets	创建、读取、写入、追加、查找和导出电子表格数据
🖼️ 幻灯片	创建和管理演示文稿，读取演示文稿内容，以及添加或删除幻灯片
✅ 任务	创建、查询、更新和完成任务；管理任务列表、子任务、评论和提醒
📚 知识库	创建和管理知识空间、节点和文档
👤 联系人	按姓名/邮箱/电话搜索用户，获取用户资料
📧 邮件	浏览、搜索和阅读邮件，发送、回复、转发邮件，管理草稿，监视新邮件
🎥 会议	搜索实时和历史会议，查看参与者和资料，分析转录内容，管理 Minutes，并协助会议
🕐 考勤	查询个人考勤打卡记录
✍️ 审批	查询审批任务，批准/拒绝/转交任务，取消实例并抄送实例
🎯 OKR	查询、创建和更新 OKR；管理目标和关键结果、对齐关系、指标及进度。
📋 项目	Meegle — 通过独立的 meegle-cli 管理工作项、日程和数据（需单独安装）
🔗 应用	创建 Spark/Miaoda 应用，发布 HTML/静态网站，运行云端生成，并管理访问范围

安装与快速开始

要求

开始之前，请确保已安装：

• Node.js（npm/npx）
• Go v1.23+ 和 Python 3（仅从源代码构建时需要）

快速开始（用户）

AI 助手注意： 如果你是帮助用户安装的 AI Agent，请直接跳转到快速开始（AI Agent），其中包含你需要完成的所有步骤。

安装

选择以下一种方法：

选项 1 — 从 npm 安装（推荐）：

npx @larksuite/cli@latest install

选项 2 — 从源代码安装：

需要 Go v1.23+ 和 Python 3。

git clone https://github.com/larksuite/cli.git
cd cli
make install

# Install CLI SKILL (required)
npx skills add larksuite/cli -y -g

配置与使用

# 1. Configure app credentials (one-time, interactive guided setup)
lark-cli config init

# 2. Log in (--recommend auto-selects commonly used scopes)
lark-cli auth login --recommend

# 3. Start using
lark-cli calendar +agenda

快速入门（AI Agent）

以下步骤适用于 AI Agent。部分步骤需要用户在浏览器中完成操作。

步骤 1 — 安装

npx @larksuite/cli@latest install

步骤 2 — 配置应用凭据

在后台运行此命令。它会输出一个授权 URL——提取该 URL 并发送给用户。用户在浏览器中完成设置后，命令会自动退出。

lark-cli config init --new

步骤 3 — 登录

与上面相同：在后台运行，提取授权 URL 并发送给用户。

lark-cli auth login --recommend

步骤 4 — 验证

lark-cli auth status

Agent 技能

技能	描述
lark-shared	应用配置、身份验证登录、身份切换、权限范围管理、安全规则（由所有其他技能自动加载）
lark-calendar	日历事件（创建/更新）、日程视图、空闲/忙碌查询、时间建议、查找会议室、回复 RSVP
lark-im	发送/回复消息、群聊管理、消息搜索、上传/下载图片和文件、表情回应
lark-doc	创建、读取、更新、搜索文档（基于 Markdown）
lark-drive	上传、下载文件，管理权限和评论
lark-markdown	创建、获取、修补和覆盖云文档原生 Markdown 文件
lark-sheets	创建、读取、写入、追加、查找、导出电子表格
lark-slides	创建和管理演示文稿、读取演示文稿内容，以及添加或移除幻灯片
lark-base	表格、字段、记录、视图、仪表盘、数据汇总与分析
lark-task	任务、任务列表、子任务、提醒、成员分配
lark-mail	浏览、搜索、阅读邮件，发送、回复、转发，管理草稿，监控新邮件
lark-contact	按姓名/邮箱/电话搜索用户，获取用户资料
lark-wiki	知识空间、节点、文档
lark-event	实时事件订阅（WebSocket）、正则路由和适合 Agent 的格式
lark-meeting	搜索正在进行或历史会议、查看参会者和资料、分析转录内容、管理会议纪要，并协助会议
lark-whiteboard	白板/图表 DSL 渲染
lark-openapi-explorer	通过官方文档探索底层 API
lark-skill-maker	自定义技能创建框架
lark-attendance	查询个人考勤打卡记录
lark-approval	查询审批任务、批准/拒绝/转交任务、撤销和抄送审批实例
lark-workflow-meeting-summary	工作流：会议纪要汇总与结构化报告
lark-workflow-standup-report	工作流：日程与待办事项汇总
lark-okr	查询、创建、更新 OKR；管理目标与关键结果、对齐关系和指标。

身份验证

命令	说明
auth login	通过交互式选择或 CLI 标志指定作用域进行 OAuth 登录
auth logout	登出并删除已存储的凭据
auth status	显示当前登录状态和已授权的作用域
auth check	验证指定作用域（退出码 0 = 正常，1 = 缺失）
auth scopes	列出应用的所有可用作用域
auth list	列出所有已通过身份验证的用户

# Interactive login (TUI guides domain and permission level selection)
lark-cli auth login

# Filter by domain
lark-cli auth login --domain calendar,task

# Recommended auto-approval scopes
lark-cli auth login --recommend

# Exact scope
lark-cli auth login --scope "calendar:calendar:read"

# Agent mode: return verification URL immediately, non-blocking
lark-cli auth login --domain calendar --no-wait
# Resume polling later
lark-cli auth login --device-code <DEVICE_CODE>

# DPoP (Demonstrating Proof of Possession) is enabled in preferred mode by default for new local credentials
lark-cli config set dpop preferred
# Or disable DPoP
lark-cli config set dpop disabled
# Or require DPoP without Bearer fallback
lark-cli config set dpop required
# Re-authorize after choosing a different policy
lark-cli auth login

# Identity switching: execute commands as user or bot
lark-cli calendar +agenda --as user
lark-cli im +messages-send --as bot --chat-id "oc_xxx" --text "Hello"

三层命令系统

CLI 提供三个粒度级别，涵盖从快速操作到完全自定义 API 调用的各种需求：

1. 快捷命令

以 + 为前缀，面向人类和 AI 设计，提供智能默认值、表格输出和试运行预览。

lark-cli calendar +agenda
lark-cli im +messages-send --chat-id "oc_xxx" --text "Hello"
lark-cli docs +create --doc-format markdown --content $'<title>Weekly Report</title>\n# Progress\n- Completed feature X'

运行 lark-cli <service> --help 查看所有快捷命令。

2. API 命令

根据 Lark OAPI 元数据自动生成，并经过评估和质量门槛筛选——100 多条命令与平台端点一一对应。

lark-cli calendar calendars list
lark-cli calendar events instance_view --params '{"calendar_id":"primary","start_time":"1700000000","end_time":"1700086400"}'

3. 原始 API 调用

直接调用任意 Lark 开放平台端点，覆盖 2500 多个 API。

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      # Full JSON response (default)
--format pretty    # Human-friendly formatted output
--format table     # Readable table
--format ndjson    # Newline-delimited JSON (for piping)
--format csv       # Comma-separated values

JSON 输出约定

使用 --format json（默认格式）时，成功和错误信封彼此不同。

成功结果写入 stdout，退出码为 0：

{ "ok": true, "identity": "user", "data": { "guid": "..." }, "meta": { "count": 1 } }

错误结果写入 stderr，退出码非零：

{ "ok": false, "identity": "user", "error": { "type": "api", "subtype": "...", "code": 99991679, "message": "...", "hint": "..." } }

要检查命令是否成功，请测试 ok == true（或检查退出码），而不是 code == 0。与原始 OpenAPI 响应（{"code": 0, "msg": "ok", ...}）不同，成功信封不包含 code 或 msg 字段；code 只会作为上游 OpenAPI 代码出现在 error 中。完整错误分类请参阅 errs/ERROR_CONTRACT.md。

分页

--page-all                  # Auto-paginate through all pages
--page-limit 5              # Max 5 pages
--page-delay 500            # 500ms between page requests

试运行

对于可能产生副作用的命令，请先使用 --dry-run 预览请求：

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

架构内省

使用 schema 检查任意 API 方法的参数、请求体、响应结构、支持的身份和作用域：

lark-cli schema
lark-cli schema calendar.events.instance_view
lark-cli schema im.messages.delete

安全与风险警告（使用前请阅读）

此工具可由 AI Agent 调用，以自动执行 Lark/Feishu 开放平台上的操作，并伴有模型幻觉、执行不可预测和提示词注入等固有风险。授权 Lark/Feishu 权限后，AI Agent 将在授权范围内以您的用户身份执行操作，这可能导致泄露敏感数据或未经授权的操作等高风险后果。请谨慎使用。

为降低这些风险，此工具默认启用了多层安全保护。不过，这些风险依然存在。我们强烈建议您不要主动修改任何默认安全设置；一旦放宽相关限制，风险将显著增加，您也需自行承担后果。

我们建议将与此工具集成的 Lark/Feishu 机器人用作私人对话助手。请勿将其添加到群聊，也不要允许其他用户与其互动，以避免权限滥用或数据泄露。

为降低访问令牌被盗相关的安全风险，CLI 会在向精确匹配的官方 Feishu/Lark HTTPS 域名发送 OpenAPI 请求时，附带一组最精简的风险控制信号。这些信号用于帮助识别异常 API 活动。此保护默认启用。发送的信息仅限于：

• 操作系统类型：macOS、Windows 或 Linux
• 设备硬件型号：例如，Mac17,9

要为当前工作区禁用此保护，请运行：

lark-cli config risk-control off

要为当前工作区启用此保护，请运行：

lark-cli config risk-control on

要为当前工作区恢复默认策略，请运行：

lark-cli config risk-control default

请充分了解所有使用风险。使用此工具即视为您自愿承担所有相关责任。

贡献

欢迎社区贡献！如果您发现 Bug 或有功能建议，请提交 Issue 或 Pull Request。

对于重大变更，我们建议您先通过 Issue 与我们讨论。

提交 PR 前，请参阅 AGENTS.md，了解贡献者和 AI Agent 使用的本地构建、测试和 PR 检查清单。

许可证

本项目采用 MIT License 授权。 运行时，本项目会调用 Lark/Feishu 开放平台 API。使用这些 API，您必须遵守以下协议和隐私政策：

• Feishu 用户服务条款
• Feishu 隐私政策
• Feishu 开放平台应用服务商安全管理规范
• Lark 用户服务条款
• Lark 隐私政策