/lark-cli

name: lark-cli
description: Use when the user wants to operate Lark or Feishu via the local lark-cli (@larksuite/cli), including install, app credentials, OAuth, readiness checks, and safe read/write boundaries.

Lark CLI (larksuite/cli)

Overview

Use this skill to help the user work through a local [`lark-cli`](https://github.com/larksuite/cli) installation from inside NextClaw.

This skill is intentionally decoupled:

• The skill owns explanation, onboarding, readiness checks, workflow choice, risk handling, and permission clarity.
• The `lark-cli` binary owns actual execution against the Lark/Feishu Open Platform APIs.

From the user’s point of view, the experience should feel complete:

• install the CLI (and optionally upstream skill assets when needed),
• configure app credentials and complete OAuth,
• verify readiness with observable commands,
• then run the real task.

Do not pretend the environment is ready when it is not. Treat browser completion, terminal success text, and real readiness as three separate things. Only observable CLI checks count as success.

Install Boundary: Upstream CLI vs NextClaw Skill

Always distinguish these three things before taking action:

• `@larksuite/cli` / `lark-cli` binary install:

`npm install -g @larksuite/cli`

• NextClaw runtime skill install:

the selectable skill must exist at `<workspace>/skills/lark-cli/SKILL.md`

• Global Agent Skill install:

a user-wide skill may exist at `~/.agents/skills/<skill-name>/SKILL.md`

• This repo's source skill:

`skills/lark-cli/SKILL.md` inside the NextClaw repository

NextClaw loads both workspace skills and global Agent Skills. They appear as separate sources in the skill picker and keep separate installation/update lifecycles.

Default NextClaw workspace:

~/.nextclaw/workspace

So the default installed skill path is:

~/.nextclaw/workspace/skills/lark-cli/SKILL.md

If the user wants the skill installed into a specific project or workspace, install it with an explicit workdir:

nextclaw skills install lark-cli --workdir <workspace>

Do not treat this upstream command as a NextClaw marketplace or workspace install:

npx skills add larksuite/cli -y -g

That upstream command installs upstream Agent Skill assets globally. When it writes to `~/.agents/skills/`, NextClaw can show the result under `Global skills`, but it does not install the NextClaw-packaged `lark-cli` skill or join the NextClaw marketplace lifecycle.

Deterministic Integration Recipe

When the user says "help me connect Feishu/Lark in NextClaw" or "make this skill actually work", follow this exact order and do not skip steps.

Step 0: Verify the NextClaw side first

Check the real NextClaw workspace path before touching `lark-cli`.

• Default workspace: `~/.nextclaw/workspace`
• Expected installed skill file:

`<workspace>/skills/lark-cli/SKILL.md`

If the user says they already installed the skill, verify that file exists. If it does not exist, install it with:

nextclaw skills install lark-cli --workdir <workspace>

Do not start debugging Feishu OAuth before this NextClaw-side path is confirmed.

Step 1: Verify the upstream CLI binary

Run:

command -v lark-cli

If it fails, check common Node bin locations before claiming the CLI is missing:

• `~/.nvm/versions/node/*/bin`
• `/opt/homebrew/bin`
• `/usr/local/bin`

If `lark-cli` exists in one of those directories but is not on `PATH`, use a one-off PATH prefix for the current command session, for example:

PATH=$HOME/.nvm/versions/node/v22.16.0/bin:$PATH lark-cli --help

Only if the binary truly does not exist should you install it:

npm install -g @larksuite/cli

Step 2: Check current readiness before starting new flows

Run these first:

lark-cli config show
lark-cli auth status
lark-cli doctor

Interpret them in this order:

• `config show` says "Not configured yet" or `doctor` shows `config_file=fail`

-> configuration is missing; go to Step 3

• `auth status` shows `identity: "bot"` and "No user logged in"

-> config exists but user login is missing; go to Step 4

• `auth status` shows `identity: "user"` and `doctor` is all pass

-> environment is ready; go to Step 5

Do not start `config init` or `auth login` blindly before checking current state.

Step 3: Configure the app exactly once

Use the browser-based config flow:

lark-cli config init --new

For agent-style execution:

• run it once,
• capture the printed browser URL,
• send that URL to the user,
• keep the same process alive until it exits,
• then verify with `config show` and `doctor`.

Success means all of these are true:

• the original `config init --new` process exits with code `0`
• `lark-cli config show` displays a concrete `appId`
• `lark-cli doctor` reports `config_file=pass`
• `lark-cli doctor` reports `app_resolved=pass`

Do not rerun `config init --new` just because the terminal is still waiting. Do not treat "the user opened the page" as success.

Step 4: Log in as a user exactly once

Prefer the two-stage device flow:

lark-cli auth login --recommend --no-wait --json

This returns:

• `verification_url`
• `device_code`

Then immediately start the single polling process:

lark-cli auth login --device-code <DEVICE_CODE>

Agent behavior must be:

• show `verification_url` to the user
• start exactly one `--device-code` polling process
• wait for that same process to finish
• then verify with `auth status` and `doctor`

Success means all of these are true:

• the `--device-code` process exits with code `0`
• `lark-cli auth status` shows `identity: "user"`
• `lark-cli auth status` includes user info such as `userName` / `userOpenId`
• `lark-cli doctor` reports `token_exists=pass`
• `lark-cli doctor` reports `token_local=pass`
• ideally `lark-cli doctor` reports `token_verified=pass`

If `identity` is still `bot`, the login is no