SuperAPI AI Directory

lark-cli-router

Coding & development

View repository

Updated 10-15 20:05

About this skill

Lark CLI Router

This skill is used to larksuite/cli and riba2534/feishu-cli route between them, rather than replace them.

The goal is simple:

  • When the official CLI should be used, do not mistakenly use the document-oriented tool
  • When the document-oriented tool should be used, do not force the official CLI as a fallback
  • When a task must be executed but the local machine lacks the CLI, install the correct one first
  • If you can install only one, do not install both

Make a judgment first

First determine which type of task the user wants:

  1. 分析/对比/选型
  2. 真正执行 CLI 操作

If it is only analysis, comparison, writing a plan, or explaining commands, do not install a CLI just in case.

If commands actually need to be executed, then proceed to the routing and installation process below.

Routing rules

Scenarios where lark-cli is preferred

By default, prefer the official lark-cli. It is suitable for "general-purpose operations across the entire platform":

  • The user explicitly requests the official CLI,larksuite/cli、lark-cli
  • The task is a general Feishu/Lark OpenAPI operation, not document conversion
  • Involves IM / Docs / Base / Calendar / Mail / Tasks / VC / Wiki / Workflow and other platform domains
  • The user wants a more standard, long-term maintained, Agent-friendly entry point
  • The task leans toward resource management, authentication, and cross-domain orchestration, rather than Markdown fidelity conversion

Typical examples:

  • "Use the CLI to check calendar events"
  • "Configure the Lark app and log in"
  • "Operate Base, Calendar, Mail, Task"
  • "Use the official CLI to run through a Feishu platform workflow"

Scenarios where feishu-cli is preferred

When the core of the task is "document content conversion/migration/fidelity import and export", prefer feishu-cli:

  • Import Markdown into Feishu documents
  • Export Feishu documents as Markdown
  • Import Mermaid into Feishu whiteboards
  • Import PlantUML into Feishu whiteboards
  • Large document migration, complex table splitting, chart degradation fallback
  • Migrating knowledge base content, with the focus on content structure fidelity

Typical examples:

  • "Publish this Markdown as a Feishu document"
  • "Export this Feishu document as Markdown and download the images"
  • "Turn the Mermaid in the README into a Feishu whiteboard"
  • "Batch migrate technical documents to Feishu"

Scenarios where combined calls are allowed

In the following cases, the two CLIs may be used in combination:

  • First use feishu-cli to complete Markdown/document conversion, then use lark-cli for subsequent platform management
  • Document content needs high-fidelity import, but afterward Calendar/Base/Task/permission orchestration still needs to be done
  • The user explicitly requests "use both, and combine their strengths"

When combining calls, follow this order:

  1. First use feishu-cli to handle content conversion
  2. Then use lark-cli for platform-level operations

Do not reverse it by doing platform orchestration first and then going back to handle high-fidelity content migration, unless the user explicitly requests it.

Clarify priorities

Make decisions according to the following priorities:

  1. The user explicitly specifies a certain CLI: obey it first
  2. The user's task clearly belongs to document conversion: prioritize feishu-cli
  3. The user's task clearly belongs to general platform APIs: prioritize lark-cli
  4. Contains both types of goals at the same time: combined invocation
  5. Still uncertain: default to lark-cli,并在回应里说明这是基于“官方优先、平台通用优先”的推断

Check the environment before starting

Before actually executing, first check whether the command exists:

command -v lark-cli
command -v feishu-cli

Check the version if necessary:

lark-cli --version
feishu-cli --version

Rules:

  • Only check the CLI that will be used; do not meaninglessly install the whole bundle
  • If it is a combined invocation, check the two CLIs separately
  • If already installed, continue directly and do not install repeatedly

Handling when not installed

If the target CLI does not exist, and the current task requires actually executing commands, install it.

Install lark-cli

Prefer the installation method recommended in the repository README:

npm install -g @larksuite/cli
npx skills add larksuite/cli -y -g
lark-cli --version

After installation, first-time use usually also requires:

lark-cli config init
lark-cli auth login --recommend

Note:

  • lark-cli It is not just installing the npm package; the README also requires installing the companion skill
  • If npm is unavailable, then consider installing from source; do not prioritize the heavier path

Install feishu-cli

Prefer the installation method recommended in the repository README:

curl -fsSL https://raw.githubusercontent.com/riba2534/feishu-cli/main/install.sh | bash
feishu-cli --version

If the one-click installation is not suitable for the current environment, then use the alternative method given in the README:

go install github.com/riba2534/feishu-cli@latest

After installation, the common initialization method is:

feishu-cli config init

If the task requires search or user-space capabilities, then continue:

feishu-cli auth login

When neither is installed

The rules are strict:

  • Only install the one most needed for the current task
  • Only install both when a combined invocation is explicitly needed
  • After installation, immediately verify that the command is available, then continue the task

Common routing templates

Template 1: Official platform operations

When the user wants to “use the CLI to operate Feishu platform capabilities,” prioritize:

lark-cli <domain> <subcommand>

Suitable for:

  • Calendar
  • Base
  • Mail
  • Tasks
  • Cross-domain platform orchestration

Template 2: Markdown document import

When the user wants to “send local documents to Feishu,” prioritize:

feishu-cli doc import <file.md> --title "<title>"

If images also need to be uploaded, or charts/tables need to be processed concurrently, add parameters according to the task.

Template 3: Feishu document export to Markdown

feishu-cli doc export <document_id> -o <output.md> --download-images

Template 4: Mermaid / PlantUML

For chart import, Feishu whiteboard, or editable vector graphics, prioritize feishu-cli。

Template 5: Combined invocation

First:

feishu-cli doc import <file.md> --title "<title>"

Then:

lark-cli <domain> <subcommand>

Template 6: Transfer ownership after creating a document (must be executed)

After creating a Feishu document by any method, ownership must be transferred to the user immediately.

The document is created with the bot identity, so the transfer must also be executed with the bot identity:

# 1. 获取用户 open_id(首次执行后可复用)
lark-cli contact +get-user --as user

# 2. 转移所有权(--as bot,因为文档归属 bot)
lark-cli drive permission.members transfer_owner \
  --as bot \
  --params '{"token":"<document_id>","type":"docx","need_notification":true}' \
  --data '{"member_type":"openid","member_id":"<user_open_id>"}'

The user's open_id:ou_b85d465b2260445e69b40b10a33abee1

Rules:

  • Whether through feishu-cli doc import or lark-cli docs +create creation, this step must be executed
  • No need for the user to remind proactively; execute automatically after creation is complete
  • type The field corresponds to the document type; the new document type is docx

What to explain when responding to the user

When you make a routing decision, briefly explain:

  • Why choose this CLI
  • Whether it was installed first because the local machine lacks the CLI
  • If it is a combined call, which part is each of the two CLIs responsible for

Do not just say "I'll handle it for you"; explain the basis for your choice clearly.

Failure handling

If installation or execution fails:

  • Report at which step the failure occurred
  • Provide a summary of the actual error
  • Explain the next minimal executable action

Do not pretend the command has already executed successfully when the CLI is unavailable.

Prohibitions

  • Do not assume by default just because you see the word "Feishu" feishu-cli
  • Do not assume by default just because you see the word "CLI" lark-cli
  • Do not proactively modify the user's machine when only analysis is needed
  • Do not execute directly without checking whether the command exists
  • Do not install both CLIs when a combined call is not needed

One-sentence strategy

平台通用操作优先 lark-cli,文档高保真转换优先 feishu-cli,跨两类场景时组合调用,缺哪个装哪个。