跳到正文
Kale的数字花园
目录 文章
/11 分钟/10 阅读/0 评论

Lark CLI 官方版从零搭建指南：MD 自动发布到飞书/Lark 在线文档

前往 Node.js 官网下载 LTS 版本： 下载 Windows Installer（ ），双击安装，一路默认即可。 打开 CMD 或 PowerShell，执行： 两个都能输出版本号就算成功 ✅ 这个命令会自动完成： 看到版本号输出即

面试#教程

目标：在一台全新电脑上，使用飞书官方 CLI 工具（@larksuite/cli），实现将本地 Markdown 文件自动发布为飞书/Lark 在线文档，并转移文档所有权给开发者本人。

适用系统：Windows 10/11

预计耗时：15~20 分钟（官方工具大幅简化了流程）

工具来源：字节跳动/飞书官方团队维护，MIT 开源协议

GitHub：https://github.com/larksuite/cli

与第三方 feishu-cli 的区别

维度 riba2534/feishu-cli（第三方） @larksuite/cli（官方）
维护方 社区开发者 飞书/Lark 官方团队
安装方式 下载 exe + 手动配 PATH npx @larksuite/cli@latest install 一行搞定
应用创建 手动去开放平台创建 lark-cli config init 交互式一键创建
配置文件 手动编辑 config.yaml 交互式引导自动生成
登录认证 手动指定 scope --recommend 自动选择常用权限
业务覆盖 主要文档操作 18 大业务域、200+ 命令
AI Agent 基础支持 26 个内置 AI Agent Skill
飞书/Lark 改 base_url 切换 自动识别，无需手动切换
命令风格 feishu-cli doc import 三层架构（Shortcuts / API / Raw）

全局流程概览

flowchart TD
    A[1. 安装 Node.js] --> B[2. 安装 Lark CLI]
    B --> C[3. 初始化应用配置]
    C --> D[4. OAuth 登录认证]
    D --> E[5. 导入 MD 到飞书/Lark]
    E --> F[6. 转移文档所有权]
    F --> G(完成)

    style A fill:#FF9800,color:#fff
    style B fill:#4CAF50,color:#fff
    style G fill:#2196F3,color:#fff

💡 对比旧版教程少了 5 个步骤（手动创建应用、手动配权限、手动配重定向 URL、发布应用、手写 config.yaml），官方 CLI 全自动化了。

第一步：安装 Node.js（前置条件）

@larksuite/cli 是 npm 包，必须先有 Node.js 环境。

1.1 下载安装 Node.js

前往 Node.js 官网下载 LTS 版本：

下载地址：https://nodejs.org/

下载 Windows Installer（.msi），双击安装，一路默认即可。

1.2 验证安装

打开 CMD 或 PowerShell，执行：

node --version
npm --version

两个都能输出版本号就算成功 ✅

💡 推荐 Node.js v18+，实测 v16 及以下可能有兼容问题。

第二步：安装 Lark CLI

2.1 一行命令安装

npx @larksuite/cli@latest install

这个命令会自动完成：

  • 下载最新版 lark-cli 二进制文件
  • 安装到全局 PATH
  • 安装必要的 CLI Skills

⚠️ 如果 npm 配置了 ignore-scripts true，会导致安装失败。请确认没有这个配置：

npm config get ignore-scripts
# 应该返回 false 或 undefined

2.2 验证安装

lark-cli --version

看到版本号输出即安装成功 ✅

💡 如果提示 lark-cli 不是可识别的命令，重启终端窗口试试。npm 全局安装后 PATH 生效需要重开终端。

第三步：初始化应用配置

🎉 这一步替代了旧版教程的第 2~6 步！ 官方 CLI 支持一键创建飞书应用并自动配置，不需要手动去开放平台操作。

方式一：一键创建新应用（推荐）

lark-cli config init --new

执行后会自动打开浏览器，引导你：

  1. 登录飞书/Lark 开放平台
  2. 一键创建应用（自动命名为 lark-cli 相关名称）
  3. 自动开通所需权限
  4. 自动配置重定向 URL
  5. 自动发布应用

浏览器中完成操作后，终端会显示配置成功 ✅

方式二：使用已有应用

如果你已经在开放平台创建过应用，可以直接填入凭证：

lark-cli config init

按交互式提示输入：

  • App ID（以 cli_ 开头）
  • App Secret

3.3 确认配置生效

lark-cli auth status

如果返回配置相关信息（即使显示未登录），说明配置已生效 ✅

（参考）手动在开放平台创建应用

如果 config init --new 不可用或遇到问题，可以手动操作：

  1. 打开浏览器访问：
  2. 点击 "Create App" → "Build an App" → "Self-built app"
  3. 填写应用名称和描述
  4. 在 "Credentials" 页面记录 App ID 和 App Secret
  5. 在 "Permissions & Scopes" 中开通以下权限：

必需权限清单

权限标识 权限说明
docx:document 查看、编辑文档
docx:document:readonly 获取文档内容
drive:drive 管理云空间文件
drive:drive:readonly 查看云空间文件
drive:drive:upload 上传文件
drive:file:download 下载文件
drive:file:upload 上传所有文件
docs:permission.member:create 添加协作者
docs:permission.member:readonly 查看协作者
docs:permission.member:delete 删除协作者
docs:permission.setting:write 更新公开权限
contact:user.base:readonly 获取用户基本信息
auth:user.id:read 获取用户身份信息

可选权限

权限标识 权限说明
search:docs:read 搜索云文档
wiki:wiki:readonly 查看知识库
wiki:wiki 管理知识库
board:board 查看和管理画板
  1. 在 "Security Settings" 中添加重定向 URL：http://127.0.0.1:9768/callback
  2. 在 "Version Management" 中创建版本并发布应用
  3. 然后执行 lark-cli config init，按提示输入 App ID 和 App Secret

第四步：OAuth 登录认证

4.1 执行登录

lark-cli auth login --recommend

--recommend 会自动选择常用的权限范围（scopes），不需要手动指定。

4.2 浏览器授权

命令执行后会自动打开浏览器：

  1. 在飞书/Lark 授权页面点击 "同意授权" / "Allow"
  2. 浏览器会跳转到回调页面（可能显示"无法访问此网站"，这是正常的）
  3. CLI 会自动捕获回调并完成认证

4.3 确认登录成功

lark-cli auth status

返回类似以下内容即成功 ✅：

{
  "logged_in": true,
  "access_token_valid": true,
  "refresh_token_valid": true
}

4.4 （备选）Device Flow 登录

如果自动打开浏览器不成功，可以使用 Device Flow：

# 生成授权链接（不阻塞终端）
lark-cli auth login --recommend --no-wait

命令会输出一个授权 URL 和 Device Code，把 URL 复制到浏览器完成授权后：

# 用 Device Code 完成登录
lark-cli auth login --device-code <DEVICE_CODE>

4.5 其他认证命令

# 查看所有已认证用户
lark-cli auth list

# 检查某个 scope 是否已授权
lark-cli auth check --scope "docx:document"

# 列出应用所有可用 scope
lark-cli auth scopes

# 登出
lark-cli auth logout

第五步：导入 MD 文件到飞书/Lark

Lark CLI 提供两种方式创建文档，按需选择。

方式一：快捷命令（Shortcuts）—— 推荐

直接用 Markdown 内容创建飞书在线文档：

lark-cli docs +create --api-version v2 --doc-format markdown --content "$(cat 'C:\Users\你的用户名\Desktop\技术方案.md')"

或者用 PowerShell 读取文件内容：

$content = Get-Content "C:\Users\你的用户名\Desktop\技术方案.md" -Raw
lark-cli docs +create --api-version v2 --doc-format markdown --content $content

参数说明：

参数 说明
--api-version v2 使用文档 API v2
--doc-format markdown 内容格式为 Markdown
--content 文档内容（Markdown 格式）

方式二：Markdown 原生命令

创建 Drive 原生的 .md 文件：

lark-cli markdown create --file "C:\Users\你的用户名\Desktop\技术方案.md"

💡 两种方式的区别：

  • docs +create：创建飞书在线文档（docx），支持更丰富的格式（表格、画板等）
  • markdown create：创建 Drive 原生 Markdown 文件（.md），保持原始格式

5.3 记录文档 ID

创建成功后会返回文档信息，记录下文档 ID（一串字母数字），下一步要用。

💡 可以用 --format pretty 获得更易读的输出：

lark-cli docs +create --api-version v2 --doc-format markdown --content "..." --format pretty

第六步：转移文档所有权

⚠️ 为什么需要这一步？ 通过 API 创建的文档，所有者是应用（机器人），不是你本人。直接打开会提示"无权限"。必须转移所有权。

6.1 添加协作者权限

lark-cli drive +permission-add \
  --token "文档ID" \
  --type docx \
  --member-type email \
  --member-id "你的飞书邮箱@公司域名.com" \
  --perm full_access

6.2 转移所有权

lark-cli drive +permission-transfer \
  --token "文档ID" \
  --type docx \
  --member-type email \
  --member-id "你的飞书邮箱@公司域名.com"

6.3 验证

打开文档链接，确认能正常编辑 ✅

💡 可以用以下命令查看文档协作者列表：

lark-cli drive +permission-list --token "文档ID" --type docx

🎯 一键脚本（日常使用）

PowerShell 版本（Windows 原生）

# lark-publish.ps1 - 一键发布 MD 到飞书/Lark 文档
# 用法: .\lark-publish.ps1 -MdFile "C:\path\to\file.md" -Title "标题" -Email "your@email.com"

param(
    [Parameter(Mandatory=$true)]
    [string]$MdFile,

    [Parameter(Mandatory=$false)]
    [string]$Title = "",

    [Parameter(Mandatory=$true)]
    [string]$Email
)

# 读取 MD 文件内容
if (-not (Test-Path $MdFile)) {
    Write-Host "❌ 文件不存在: $MdFile" -ForegroundColor Red
    exit 1
}

$content = Get-Content $MdFile -Raw -Encoding UTF8

# 如果指定了标题，在内容前插入一级标题
if ($Title) {
    $content = "# $Title`n`n$content"
}

Write-Host "📄 正在发布: $MdFile" -ForegroundColor Cyan

# 创建飞书文档
$result = lark-cli docs +create --api-version v2 --doc-format markdown --content $content --format json 2>&1
Write-Host $result

# 提取文档 ID
if ($result -match '"document_id"\s*:\s*"([A-Za-z0-9]+)"') {
    $docId = $matches[1]
} elseif ($result -match '"obj_token"\s*:\s*"([A-Za-z0-9]+)"') {
    $docId = $matches[1]
} elseif ($result -match '([A-Za-z0-9]{20,})') {
    $docId = $matches[1]
} else {
    Write-Host "❌ 创建失败，无法获取文档 ID" -ForegroundColor Red
    exit 1
}

Write-Host "📝 文档 ID: $docId" -ForegroundColor Green

# 添加完全访问权限
Write-Host "🔐 正在添加权限..." -ForegroundColor Cyan
lark-cli drive +permission-add --token $docId --type docx --member-type email --member-id $Email --perm full_access

# 转移所有权
Write-Host "🔄 正在转移所有权..." -ForegroundColor Cyan
lark-cli drive +permission-transfer --token $docId --type docx --member-type email --member-id $Email

Write-Host ""
Write-Host "✅ 发布完成！" -ForegroundColor Green
Write-Host "📎 文档链接: https://feishu.cn/docx/$docId" -ForegroundColor Yellow

Bash 版本（Git Bash / WSL）

#!/bin/bash
# lark-publish.sh - 一键发布 MD 到飞书/Lark 文档
# 用法: ./lark-publish.sh <md文件路径> [文档标题] <你的邮箱>

MD_FILE="$1"
TITLE="$2"
EMAIL="$3"

if [ -z "$MD_FILE" ] || [ -z "$EMAIL" ]; then
  echo "Usage: ./lark-publish.sh <md_file> [title] <email>"
  exit 1
fi

# 读取 MD 文件
if [ ! -f "$MD_FILE" ]; then
  echo "❌ 文件不存在: $MD_FILE"
  exit 1
fi

CONTENT=$(cat "$MD_FILE")

# 如果指定了标题，在内容前插入
if [ -n "$TITLE" ]; then
  CONTENT="# $TITLE\n\n$CONTENT"
fi

echo "📄 正在发布: $MD_FILE"

# 创建飞书文档
RESULT=$(lark-cli docs +create --api-version v2 --doc-format markdown --content "$CONTENT" --format json 2>&1)
echo "$RESULT"

# 提取文档 ID
DOC_ID=$(echo "$RESULT" | grep -oP '"document_id"\s*:\s*"\K[A-Za-z0-9]+' || echo "$RESULT" | grep -oE '[A-Za-z0-9]{20,}' | head -1)

if [ -z "$DOC_ID" ]; then
  echo "❌ 创建失败，无法获取文档 ID"
  exit 1
fi

echo "📝 文档 ID: $DOC_ID"

# 添加完全访问权限
echo "🔐 正在添加权限..."
lark-cli drive +permission-add --token "$DOC_ID" --type docx --member-type email --member-id "$EMAIL" --perm full_access

# 转移所有权
echo "🔄 正在转移所有权..."
lark-cli drive +permission-transfer --token "$DOC_ID" --type docx --member-type email --member-id "$EMAIL"

echo ""
echo "✅ 发布完成！"
echo "📎 文档链接: https://feishu.cn/docx/$DOC_ID"

使用方法：

# PowerShell
.\lark-publish.ps1 -MdFile "C:\Users\msn\Desktop\技术方案.md" -Title "技术方案" -Email "wangkunlun@poolking-tech.com"

# Bash
chmod +x lark-publish.sh
./lark-publish.sh "C:/Users/msn/Desktop/技术方案.md" "技术方案" "wangkunlun@poolking-tech.com"

支持的 Markdown 特性

Lark CLI 通过飞书文档 API v2 创建文档，支持标准 Markdown 语法：

语法 说明 示例
标题 # ~ ###### # 一级标题
段落/文本 普通文本 直接写
粗体 **文本** 粗体
斜体 *文本* 斜体
删除线 ~~文本~~ 删除线
行内代码 `代码` code
链接 [文字](URL) 链接
无序列表 - 项目 嵌套用缩进
有序列表 1. 项目 支持嵌套
任务列表 - [ ] / - [x] 待办/已完成
代码块 ```语言 带语法高亮
表格 ` 表头
图片 ![描述](URL) 支持
引用 > 文本 支持嵌套
分割线 --- 水平线

⚠️ 注意：docs +create --doc-format markdown 使用飞书内置的 Markdown 导入引擎。如果需要 Mermaid 图表转画板、PlantUML 等高级转换功能，建议使用第三方 riba2534/feishu-cli 的 doc import 命令，它在 Markdown ↔ 飞书文档双向转换方面做了更深入的适配。

Lark CLI 三层命令架构

Lark CLI 的命令设计分三层，按需选择粒度：

flowchart LR
    A["快捷命令（Shortcuts）<br>+create / +agenda<br>人机友好，智能默认值"] --> B["API 命令<br>calendar.events.list<br>与平台端点一一对应"]
    B --> C["Raw API 调用<br>api GET /open-apis/...<br>覆盖 2500+ API"]

    style A fill:#4CAF50,color:#fff
    style B fill:#2196F3,color:#fff
    style C fill:#9C27B0,color:#fff

1. 快捷命令（Shortcuts）

以 + 为前缀，最常用，智能默认值：

# 创建文档
lark-cli docs +create --api-version v2 --doc-format markdown --content '# Hello World'

# 查看今日日程
lark-cli calendar +agenda

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

2. API 命令

与飞书开放平台端点一一对应，100+ 精选命令：

# 列出日历
lark-cli calendar calendars list

# 查看日程
lark-cli calendar events instance_view --params '{"calendar_id":"primary"}'

3. Raw API 调用

直接调用任意飞书 API，覆盖 2500+ 端点：

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

# POST 请求
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      # 完整 JSON 响应（默认）
--format pretty    # 人性化格式输出
--format table     # 易读表格
--format ndjson    # 换行分隔 JSON（适合管道处理）
--format csv       # 逗号分隔值

分页控制

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

Dry Run（预览不执行）

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

Schema 自省（查看 API 参数结构）

# 查看所有可用 API
lark-cli schema

# 查看某个 API 的参数详情
lark-cli schema docs.document.create

身份切换

# 以用户身份执行
lark-cli calendar +agenda --as user

# 以机器人身份执行
lark-cli im +messages-send --as bot --chat-id "oc_xxx" --text "Hello"

常见问题排障

问题 原因 解决方案
npx: command not found 未安装 Node.js 回到第一步安装 Node.js
lark-cli: command not found 安装后未重开终端 关闭终端重新打开
npm install fails with ignore-scripts npm 配置了 ignore-scripts true 执行 npm config set ignore-scripts false
认证失败 / Token 过期 未登录或 Token 已失效 执行 lark-cli auth login --recommend 重新认证
Permission denied 应用权限未开通 执行 lark-cli config init --new 重新配置，或手动去开放平台开通权限
文档创建成功但无法访问 未转移所有权 执行第六步的权限添加和所有权转移
App not published 应用未发布 执行 lark-cli config init --new 或手动去开放平台发布
Scope xxx not granted 登录时未授权该权限 执行 lark-cli auth login --scope "xxx" 补充授权
config init --new 浏览器没打开 浏览器关联问题 手动复制终端输出的 URL 到浏览器
docs +create 报错 登录身份或权限不足 确认已用 auth login --recommend 登录
飞书/Lark 切换问题 config 中域名不对 删除配置重新执行 lark-cli config init，选择正确的平台

文件结构总览

搭建完成后，CLI 相关文件存放在用户主目录：

flowchart LR
    subgraph local[本地电脑]
        A[Markdown 文件] --> B[lark-cli]
        C["~/.lark-cli/<br>config + token"] --> B
    end
    B -->|"docs +create"| D[飞书/Lark 云文档]
    B -->|"drive +permission"| E[权限管理 + 所有权转移]

快速命令速查表

# ========== 安装 & 配置 ==========
# 安装 CLI
npx @larksuite/cli@latest install

# 检查版本
lark-cli --version

# 初始化配置（一键创建应用）
lark-cli config init --new

# 使用已有应用配置
lark-cli config init

# ========== 认证 ==========
# 登录（推荐）
lark-cli auth login --recommend

# 查看登录状态
lark-cli auth status

# 查看所有已认证用户
lark-cli auth list

# 列出可用 scope
lark-cli auth scopes

# 登出
lark-cli auth logout

# ========== 文档操作 ==========
# 创建文档（Markdown 内容）
lark-cli docs +create --api-version v2 --doc-format markdown --content "# 标题"

# 创建原生 Markdown 文件
lark-cli markdown create --file "文件.md"

# ========== 权限管理 ==========
# 添加协作者
lark-cli drive +permission-add --token "文档ID" --type docx --member-type email --member-id "邮箱" --perm full_access

# 转移所有权
lark-cli drive +permission-transfer --token "文档ID" --type docx --member-type email --member-id "邮箱"

# 查看协作者
lark-cli drive +permission-list --token "文档ID" --type docx

# ========== 工具 ==========
# 查看 API Schema
lark-cli schema

# Dry Run 预览
lark-cli docs +create --doc-format markdown --content "test" --dry-run

# 查看帮助
lark-cli --help
lark-cli docs --help
lark-cli drive --help

📌 飞书版 ↔ Lark 版切换

官方 CLI 同时支持飞书和 Lark，在 config init 时会自动识别你要用哪个平台：

# 重新配置，选择另一个平台
lark-cli config init

按交互式提示选择飞书或 Lark，然后重新登录即可。

⚠️ 切换后之前的 Token 会失效，需要重新执行 lark-cli auth login --recommend。

参考链接

资源 链接
GitHub 仓库 https://github.com/larksuite/cli
README 中文版 https://github.com/larksuite/cli/blob/main/README.zh.md
npm 包 https://www.npmjs.com/package/@larksuite/cli
官方文档（中文） https://open.feishu.cn/document/mcp_open_tools/feishu-cli-let-ai-actually-do-your-work-in-feishu
官方文档（英文） https://open.larksuite.com/document/mcp_open_tools/feishu-cli-let-ai-actually-do-your-work-in-feishu
飞书 CLI 官网页 https://www.feishu.cn/feishu-cli
相关阅读

评论 0

登录后评论

评论需要登录。生产环境使用 GitHub 登录，本地可前往 登录页 使用开发登录。

还没有评论，来抢沙发。