cli Documentation

File: README.md Copy Chapter

lark-cli

中文版 | English

The official Lark/Feishu CLI tool, maintained by the larksuite team — built for humans and AI Agents. Covers core business domains including Messenger, Docs, Base, Sheets, Slides, Calendar, Mail, Tasks, Meetings, Markdown, and more, with 200+ commands and 26 AI Agent Skills.

Install · AI Agent Skills · Auth · Commands · Advanced · Enterprise · Security · Contributing

Why lark-cli? Copy Chapter

• Agent-Native Design — 24 structured Skills out of the box, compatible with popular AI tools — Agents can operate Lark with zero extra setup
• Wide Coverage — 18 business domains, 200+ curated commands, 26 AI Agent Skills
• AI-Friendly & Optimized — Every command is tested with real Agents, featuring concise parameters, smart defaults, and structured output to maximize Agent call success rates
• Open Source, Zero Barriers — MIT license, ready to use, just npm install
• Up and Running in 3 Minutes — One-click app creation, interactive login, from install to first API call in just 3 steps
• Secure & Controllable — Input injection protection, terminal output sanitization, OS-native keychain credential storage
• Three-Layer Architecture — Shortcuts (human & AI friendly) → API Commands (platform-synced) → Raw API (full coverage), choose the right granularity

Personal or Enterprise? Copy Chapter

💡 For AI Agents: append .md to any Open Platform doc URL to fetch it as raw Markdown, e.g. embed-feishu-cli-in-agent.md.

Features Copy Chapter

Installation & Quick Start Copy Chapter

Requirements Copy Section

Before you start, make sure you have:

• Node.js (npm/npx)
• Go v1.23+ and Python 3 (only required for building from source)

Quick Start (Human Users) Copy Section

Note for AI assistants: If you are an AI Agent helping the user with installation, jump directly to Quick Start (AI Agent), which contains all the steps you need to complete.

Install

Choose one of the following methods:

Option 1 — From npm (recommended):

npx @larksuite/cli@latest install

Option 2 — From source:

Requires Go v1.23+ and 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

Configure & Use

# 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

Quick Start (AI Agent) Copy Chapter

The following steps are for AI Agents. Some steps require the user to complete actions in a browser.

Step 1 — Install

npx @larksuite/cli@latest install

Step 2 — Configure app credentials

Run this command in the background. It will output an authorization URL — extract it and send it to the user. The command exits automatically after the user completes the setup in the browser.

lark-cli config init --new

Step 3 — Login

Same as above: run in the background, extract the authorization URL and send it to the user.

lark-cli auth login --recommend

Step 4 — Verify

lark-cli auth status

Agent Skills Copy Chapter

Authentication Copy Chapter

# 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>

# 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"

Three-Layer Command System Copy Chapter

The CLI provides three levels of granularity, covering everything from quick operations to fully custom API calls:

1. Shortcuts Copy Section

Prefixed with +, designed to be friendly for both humans and AI, with smart defaults, table output, and dry-run previews.

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'

Run lark-cli <service> --help to see all shortcut commands.

2. API Commands Copy Section

Auto-generated from Lark OAPI metadata, curated through evaluation and quality gates — 100+ commands mapped 1:1 to platform endpoints.

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

3. Raw API Calls Copy Section

Call any Lark Open Platform endpoint directly, covering 2500+ APIs.

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\"}"}'

Advanced Usage Copy Chapter

Output Formats Copy Section

--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 Output Contract Copy Section

With --format json (the default), success and error envelopes are distinct.

Success goes to stdout, exit code 0:

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

Errors go to stderr, non-zero exit code:

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

To check whether a command succeeded, test ok == true (or the exit code) — not code == 0. Unlike raw OpenAPI responses ({"code": 0, "msg": "ok", ...}), the success envelope carries no code or msg field; code appears only inside error as the upstream OpenAPI code. See errs/ERROR_CONTRACT.md for the full error taxonomy.

Pagination Copy Section

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

Dry Run Copy Section

For commands that may have side effects, preview the request with --dry-run first:

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

Schema Introspection Copy Section

Use schema to inspect any API method's parameters, request body, response structure, supported identities, and scopes:

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

Security & Risk Warnings (Read Before Use) Copy Chapter

This tool can be invoked by AI Agents to automate operations on the Lark/Feishu Open Platform, and carries inherent risks such as model hallucinations, unpredictable execution, and prompt injection. After you authorize Lark/Feishu permissions, the AI Agent will act under your user identity within the authorized scope, which may lead to high-risk consequences such as leakage of sensitive data or unauthorized operations. Please use with caution.

To reduce these risks, the tool enables default security protections at multiple layers. However, these risks still exist. We strongly recommend that you do not proactively modify any default security settings; once relevant restrictions are relaxed, the risks will increase significantly, and you will bear the consequences.

We recommend using the Lark/Feishu bot integrated with this tool as a private conversational assistant. Do not add it to group chats or allow other users to interact with it, to avoid abuse of permissions or data leakage.

To reduce the security risks associated with access token theft, the CLI sends a minimal set of risk-control signals with OpenAPI requests made to exact official Feishu/Lark HTTPS domains. These signals are used to help identify anomalous API activity. This protection is enabled by default. The information sent is limited to:

• Operating system type: macOS, Windows, or Linux
• Device hardware model: for example, Mac17,9

To disable this protection for the current workspace, run:

lark-cli config risk-control off

To enable this protection for the current workspace, run:

lark-cli config risk-control on

To restore the default policy for the current workspace, run:

lark-cli config risk-control default

Please fully understand all usage risks. By using this tool, you are deemed to voluntarily assume all related responsibilities.

Contributing Copy Chapter

Community contributions are welcome! If you find a bug or have feature suggestions, please submit an Issue or Pull Request.

For major changes, we recommend discussing with us first via an Issue.

Before opening a PR, see AGENTS.md for the local build, test, and PR checklist used by contributors and AI agents.

License Copy Chapter

This project is licensed under the MIT License.
When running, it calls Lark/Feishu Open Platform APIs. To use these APIs, you must comply with the following agreements and privacy policies:

• Feishu User Terms of Service
• Feishu Privacy Policy
• Feishu Open Platform App Service Provider Security Management Specifications
• Lark User Terms of Service
• Lark Privacy Policy

File: README.zh.md Copy Chapter

lark-cli

中文版 | English

飞书官方 CLI 工具，由 larksuite 团队维护 — 让人类和 AI Agent 都能在终端中操作飞书。覆盖消息、文档、多维表格、电子表格、幻灯片、日历、邮箱、任务、会议、Markdown 等核心业务域，提供 200+ 命令及 26 个 AI Agent Skills。

安装 · AI Agent Skills · 认证 · 命令 · 进阶用法 · 企业接入 · 安全 · 贡献

为什么选 lark-cli？ Copy Chapter

• 为 Agent 原生设计 — 26 个 Skills 开箱即用，适配主流 AI 工具，Agent 无需额外适配即可操作飞书
• 覆盖面广 — 18 大业务域、200+ 精选命令、26 个 AI Agent Skills
• AI 友好调优 — 每条命令经过 Agent 实测验证，提供更友好的参数、智能默认值和结构化输出，大幅提升 Agent 调用成功率
• 开源零门槛 — MIT 协议，开箱即用，npm install 即可使用
• 三分钟上手 — 一键创建应用、交互式登录授权，从安装到第一次 API 调用只需三步
• 安全可控 — 输入防注入、终端输出净化、OS 原生密钥链存储凭证
• 三层调用架构 — 快捷命令（人机友好）→ API 命令（平台同步）→ 通用调用（全 API 覆盖），按需选择粒度

个人使用还是企业集成？ Copy Chapter

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

功能 Copy Chapter

安装与快速开始 Copy Chapter

环境要求 Copy Section

开始之前，请确保具备以下条件：

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

快速开始（人类用户） Copy Section

Note for AI assistants: 如果你是 AI Agent 且正在协助用户执行安装，请直接跳转到快速开始（AI Agent）执行，那里包含你需要完成的所有步骤。

安装

以下两种方式任选其一：

方式一 — 从 npm 安装（推荐）：

npx @larksuite/cli@latest install

方式二 — 从源码安装：

需要 Go v1.23+ 和 Python 3。

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

# 安装 CLI SKILL（必需）
npx skills add larksuite/cli -y -g

配置与使用

# 1. 配置应用凭证（仅需一次，交互式引导完成）
lark-cli config init

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

# 3. 开始使用
lark-cli calendar +agenda

快速开始（AI Agent） Copy Section

以下步骤面向 AI Agent，部分步骤需要用户在浏览器中配合完成。

第 1 步 — 安装

npx @larksuite/cli@latest install

第 2 步 — 配置应用凭证

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

lark-cli config init --new

第 3 步 — 登录

同上，后台运行，提取授权链接发给用户。

lark-cli auth login --recommend

第 4 步 — 验证

lark-cli auth status

Agent Skills Copy Chapter

认证 Copy Chapter

# 交互式登录（TUI 引导选择业务域和权限级别）
lark-cli auth login

# 按域筛选
lark-cli auth login --domain calendar,task

# 推荐的自动审批 scopes
lark-cli auth login --recommend

# 精确 scope
lark-cli auth login --scope "calendar:calendar:read"

# Agent 模式：立即返回验证 URL，不阻塞
lark-cli auth login --domain calendar --no-wait
# 稍后恢复轮询
lark-cli auth login --device-code <DEVICE_CODE>

# 身份切换：以用户或机器人身份执行命令
lark-cli calendar +agenda --as user
lark-cli im +messages-send --as bot --chat-id "oc_xxx" --text "Hello"

三层命令调用 Copy Chapter

CLI 提供三种粒度的调用方式，覆盖从快速操作到完全自定义的全部场景：

1. 快捷命令（Shortcuts） Copy Section

以 + 为前缀，对人类与 AI 友好化封装，内置智能默认值、表格输出和 dry-run 预览。

lark-cli calendar +agenda
lark-cli im +messages-send --chat-id "oc_xxx" --text "Hello"
lark-cli docs +create --doc-format markdown --content $'<title>周报</title>\n# 本周进展\n- 完成了 X 功能'

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

2. API 命令 Copy Section

从飞书 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 调用 Copy Section

直接调用任意飞书开放平台端点，覆盖 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\"}"}'

进阶用法 Copy Chapter

输出格式 Copy Section

--format json      # 完整 JSON 响应（默认）
--format pretty    # 人性化格式输出
--format table     # 易读表格
--format ndjson    # 换行分隔 JSON（适合管道处理）
--format csv       # 逗号分隔值

JSON 输出契约 Copy Section

--format json（默认）下，成功与错误的信封结构不同。

成功信封写入 stdout，退出码 0：

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

错误信封写入 stderr，退出码非 0：

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

判断命令是否成功，请检查 ok == true（或进程退出码），不要用 code == 0。与原始 OpenAPI 响应（{"code": 0, "msg": "ok", ...}）不同，成功信封没有 code 和 msg 字段；code 只出现在错误信封的 error 内，含义是上游 OpenAPI 的 numeric code。完整错误分类见 errs/ERROR_CONTRACT.md。

分页 Copy Section

--page-all                  # 自动翻页获取所有数据
--page-limit 5              # 最多获取 5 页
--page-delay 500            # 每页请求间隔 500ms

Dry Run Copy Section

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

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

Schema 自省 Copy Section

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

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

安全与风险提示（使用前必读） Copy Chapter

本工具可供 AI Agent 调用以自动化操作飞书/Lark 开放平台，存在模型幻觉、执行不可控、提示词注入等固有风险；授权飞书权限后，AI Agent 将以您的用户身份在授权范围内执行操作，可能导致敏感数据泄露、越权操作等高风险后果，请您谨慎操作和使用。

为降低上述风险，工具已在多个层面启用默认安全保护，但上述风险仍然存在。我们强烈建议不要主动修改任何默认安全配置；一旦放开相关限制，上述风险将显著提高，由此产生的后果需由您自行承担。

我们建议您将对接本工具的飞书机器人作为私人对话助手使用，请勿将其拉入群聊或允许其他用户与其交互，以避免权限被滥用或数据泄露。

为降低访问令牌被盗用后的安全风险，CLI 在向飞书/Lark 官方 HTTPS 精确域名发起 OpenAPI 请求时，会随请求发送一组最小化的风控信号，用于辅助识别异常调用行为。该保护默认开启，发送的信息仅包括：

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

如需让当前 workspace 退出该保护，可执行以下命令：

lark-cli config risk-control off

如需开启当前 workspace 的保护，可执行以下命令：

lark-cli config risk-control on

恢复当前 workspace 默认策略可执行：

lark-cli config risk-control default

请您充分知悉全部使用风险，使用本工具即视为您自愿承担相关所有责任。

贡献 Copy Chapter

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

对于较大的改动，建议先通过 Issue 与我们讨论。

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

许可证 Copy Chapter

本项目基于 MIT 许可证 开源。
该软件运行时会调用 Lark/飞书开放平台的 API，使用这些 API 需要遵守如下协议和隐私政策：

• 飞书用户服务协议
• 飞书隐私政策
• 飞书开放平台独立软件服务商安全管理运营规范
• Lark User Terms of Service
• Lark Privacy Policy