> ## Documentation Index
> Fetch the complete documentation index at: https://docs.newenergycoder.club/llms.txt
> Use this file to discover all available pages before exploring further.

# 飞书 CLI 使用教程

> 飞书官方 CLI（lark-cli）安装与上手教程：一行命令让 AI Agent 操作飞书消息、文档、表格、日历等核心业务能力

飞书 CLI（`lark-cli`，npm 包名 `@larksuite/cli`）是飞书开放平台推出的官方命令行工具。只需一行命令完成安装配置，即可让你的 AI Agent 直接搜索消息、读写文档、管理多维表格、查询日程等，覆盖飞书最核心的业务域。

<Note>
  官网：[https://www.feishu.cn/feishu-cli](https://www.feishu.cn/feishu-cli)；开源地址：[https://github.com/larksuite/cli](https://github.com/larksuite/cli)。
</Note>

## 支持哪些 AI Agent

飞书 CLI 支持所有主流 AI Agent 工具，安装时会自动完成对应 Agent 的配置接入：

* Claude Code
* Codex
* Cursor
* Trae
* GitHub Copilot
* Windsurf

## 安装

<Steps>
  <Step title="准备 Node.js 环境" icon="node-js">
    安装命令通过 `npx` 执行，需要本机已安装 Node.js（npm 自带 `npx`）。
  </Step>

  <Step title="一行命令安装" icon="terminal">
    复制以下命令到终端运行：

    ```bash theme={null}
    npx @larksuite/cli@latest install
    ```
  </Step>

  <Step title="按提示完成授权" icon="key">
    安装过程中按终端提示完成飞书账号授权。授权完成后，CLI 会同时持有机器人（Bot）与用户（User）身份，按调用场景自动选择。
  </Step>

  <Step title="重启 AI Agent" icon="rotate">
    配置完成后**重启你的 AI Agent**，即可开始使用。可在终端验证安装：

    ```bash theme={null}
    lark-cli --version
    lark-cli auth status
    ```
  </Step>
</Steps>

## 核心能力

CLI 按业务域组织命令，覆盖飞书个人与企业场景，并持续快速迭代：

| 业务域   | 命令域                       | 能力举例                   |
| ----- | ------------------------- | ---------------------- |
| 消息与群聊 | `im`                      | 搜索消息和群聊、发消息、回复话题       |
| 云文档   | `docs` / `markdown`       | 创建文档、读取内容、更新正文、评论协作    |
| 云盘    | `drive`                   | 上传下载文件、管理权限、处理评论       |
| 电子表格  | `sheets`                  | 创建表格、读写单元格、批量更新        |
| 多维表格  | `base`                    | 管理数据表、字段、记录、视图、仪表盘、自动化 |
| 日历    | `calendar`                | 查日程、约会议、查忙闲、推荐时间       |
| 视频会议  | `vc` / `minutes` / `note` | 搜索会议、获取纪要和逐字稿、关联日程文档   |
| 邮件    | `mail`                    | 搜索、读取、起草、发送、回复、归档邮件    |
| 任务    | `task`                    | 创建任务、更新状态、管理清单和子任务     |
| 知识库   | `wiki`                    | 查询空间、管理节点和文档层级         |
| 通讯录   | `contact`                 | 查询用户、搜索同事、查看部门         |

此外还有审批（`approval`）、考勤（`attendance`）、OKR（`okr`）、思维笔记（`mindnotes`）、画板（`whiteboard`）等更多域，可通过 `lark-cli --help` 查看完整列表。

## 常用命令

Agent 驱动 CLI 时遵循以下优先级（同样适合人工使用）：

```bash theme={null}
# 1. 浏览某个业务域的全部命令（优先使用 + 开头的快捷命令）
lark-cli <domain> --help

# 2. 快捷命令：一条命令完成一个高层任务，优先选用
lark-cli calendar +agenda

# 3. 类型化命令：对应一个具体的开放平台 API 方法
lark-cli mail user_mailbox.messages list --user-mailbox-id me

# 4. 调用前查看方法的参数、类型与所需权限
lark-cli schema mail.user_mailbox.messages.list

# 5. 兜底：按 HTTP 路径直接调用任意开放平台接口
lark-cli api GET /open-apis/calendar/v4/calendars
```

实用旗标：

* `--jq <表达式>`：过滤 JSON 输出，只取需要的字段
* `--dry-run`：预演请求，不真正执行
* 每条命令的 `--help` 会标注风险等级：`read` / `write` / `high-risk-write`，高危写操作需要追加 `--yes` 确认

### 示例：把飞书文档读成 Markdown

```bash theme={null}
# wiki 链接先解析节点，拿到 obj_token
lark-cli wiki spaces get_node --params '{"token":"<wiki_token>"}'

# 直接抓取文档内容（JSON 输出，含正文）
lark-cli docs +fetch --doc <obj_token> --format json
```

<Tip>
  本仓库的飞书导入 Skill（`.kimi/skills/feishu-to-nec-mdx`）就是基于上述命令把飞书 Wiki 内容批量转换为本站文档的，详见仓库 `AGENTS.md`。
</Tip>

## 常见问题

<AccordionGroup>
  <Accordion title="企业管理员有办法去控制权限吗？">
    可以。企业管理员可在飞书管理后台管理应用的可用范围；CLI 调用开放平台接口所需的 API 权限（scope）在开发者后台按应用粒度申请与审批，遵循最小权限原则即可。
  </Accordion>

  <Accordion title="安装后提示命令不存在？">
    安装完成后需要**重启终端和 AI Agent**，使新配置的环境变量与 PATH 生效。若仍提示找不到 `lark-cli`，请确认 npm 全局 bin 目录已加入 PATH。
  </Accordion>

  <Accordion title="授权失败，提示“授权码已过期”？">
    授权码有时效限制，重新执行安装/授权命令，在提示后尽快完成浏览器授权即可。
  </Accordion>

  <Accordion title="调用 API 提示权限不足？">
    说明该接口对应的权限 scope 未开通或未随版本发布。到飞书开发者后台为应用添加对应权限、创建并发布新版本后重试；可先用 `lark-cli schema <service.resource.method>` 查看方法所需的权限范围。
  </Accordion>

  <Accordion title="如何在自动化任务或 AI 工作流中使用？">
    CLI 所有命令均输出结构化 JSON，配合 `--jq` 过滤字段、`--dry-run` 预演请求，可直接被脚本与 AI Agent 工作流消费；高危写操作需 `--yes` 显式确认，适合在自动化流程中做安全卡点。
  </Accordion>

  <Accordion title="CLI 和 OpenClaw 飞书官方插件是什么关系？">
    两者都是连接 AI 与飞书的官方方案，定位不同：飞书 CLI 以命令行方式让任意主流 AI Agent 调用飞书能力；OpenClaw 飞书官方插件则面向 OpenClaw 助手场景做集成。按你实际使用的 Agent 选择其一即可。
  </Accordion>

  <Accordion title="支持国际版 Lark 吗？">
    支持。CLI 同时面向飞书与 Lark（国际版），授权配置中的 `brand` 字段标识当前品牌（`feishu` / `lark`）。可通过 `lark-cli auth status` 查看当前配置。
  </Accordion>
</AccordionGroup>

## 相关资源

* [飞书 CLI 官网](https://www.feishu.cn/feishu-cli)
* [larksuite/cli GitHub 仓库](https://github.com/larksuite/cli)
* [@larksuite/cli npm 页面](https://www.npmjs.com/package/@larksuite/cli)
* [NEC openClaw 安全安装指南](/ai-tools/openclaw-setup)