lark-shared

lark-cli Shared Rules

This skill guides you on how to operate Lark resources via lark-cli and what to watch out for.

Configuration Initialization

On first use, run lark-cli config init to complete app configuration.

When helping a user initialize configuration, use the following command in the background to start the configuration flow. After launching, read the output, extract the authorization link, and send it to the user.

URL forwarding rules: When the command outputs URL fields such as verification_url, verification_uri_complete, or console_url: you must generate a QR code: call lark-cli auth qrcode to convert the URL into a QR code and display it to the user. This is a mandatory step, do not skip. Prefer generating a PNG QR code (--output); use ASCII (--ascii) only if the user explicitly requests it. URL output rules: Treat the URL as an immutable opaque string. Do not modify it in any way (including URL encoding/decoding, adding spaces or punctuation, or reassembling query parameters). Display both the QR code and the link together to the user.

# Initiate configuration (this command blocks until the user opens the link and completes the operation or it expires)
lark-cli config init --new

Authentication

Identity Types

Two identity types, switched via --as:

Identity	Flag	How to Obtain	Use Case
user (user identity)	--as user	lark-cli auth login etc.	Access user's own resources (calendar, cloud space/cloud drive/cloud storage, etc.)
bot (app identity)	--as bot	Automatic, only need appId + appSecret	App-level operations, access bot's own resources

Identity Selection Principle

The output [identity: bot/user] indicates the current identity. Bot and user behave very differently; confirm the identity matches the target requirement:

• Bot cannot see user resources: cannot access user's calendar, cloud space (cloud drive/cloud storage), documents, email, etc. For example, --as bot querying schedule returns the bot's own (empty) calendar.
• Bot cannot act on behalf of a user: sending messages is in the app's name, creating documents belongs to the bot.
• Bot permissions: only need to enable scopes in the Lark developer console; no auth login required.
• User permissions: both enabling scopes in the console and user authorization via auth login are required.

Handling Insufficient Permissions

When encountering permission-related errors, take different solutions based on the current identity type.

The error response contains key information:

• permission_violations: lists missing scopes (choose one of N)
• console_url: link to the Lark developer console for permission configuration
• hint: suggested fix command

Bot Identity (--as bot)

Provide the console_url from the error to the user as-is, and guide them to enable scopes in the console. Do not run auth login for a bot.

User Identity (--as user)

lark-cli auth login --domain <domain>           # Authorize by business domain
lark-cli auth login --scope "<missing_scope>"   # Authorize by specific scope (recommended, follows least privilege)

Rule: auth login must specify a scope (--domain or --scope). Multiple logins accumulate scopes (incremental authorization).

Agent-Initiated Authentication (Recommended)

When you as an AI agent need to help the user complete authentication, prefer split-flow to avoid blocking the same conversation turn while waiting for user authorization:

# Initiate authorization (immediately returns device_code and verification_url)
lark-cli auth login --scope "calendar:calendar:readonly" --no-wait --json

After obtaining the verification_url, send it as-is to the user as the final message in this turn, and end the turn / return control. Do not display the URL and then immediately execute --device-code blocking polling in the same turn; in agent harnesses that do not pass through intermediate output, this would cause the user to never see the URL.

After the user replies that authorization is complete, execute in a subsequent step:

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

Split-Flow Complete Steps:

Step 1: Initiate Authorization (Current Turn)

1. Execute lark-cli auth login --scope "xxx" --no-wait --json (must include --no-wait --json)
2. Extract verification_url and device_code from the JSON output
3. Generate QR code: lark-cli auth qrcode <verification_url> --output "xxx"
4. Display the URL and QR code to the user (URL first, then QR code)
5. Before ending this turn, explicitly tell the user: "Please complete the authorization and then come back to tell me it's done. I will help you with the next steps."

Step 2: Complete Authorization (Subsequent Turn)

1. Wait for the user to reply "Authorization complete"
2. You (the AI agent) execute: lark-cli auth login --device-code <device_code>
3. This command polls the authorization status and completes the login
4. If authorization succeeds, the flow ends

Key Rules:

• You must execute the --device-code command yourself, do not instruct the user to do it.
• Do not display the URL and then immediately execute --device-code in the same turn, as this would prevent the user from seeing the URL.
• Do not cache verification_url or device_code: each time authorization is needed, re-run lark-cli auth login --no-wait --json to generate new links. Do not store authorization links and device codes in context for later reuse.

Update Check

After executing a lark-cli command, if a new version is detected, the JSON output will contain a _notice.update field (with message, command, etc.).

When you see _notice.update in the output, after completing the user's current request, proactively offer to update for the user:

1. Inform the user of the current version and the latest version number
2. Offer to execute the update (updates both CLI and Skills):

   lark-cli update
   

3. After the update completes, remind the user: Exit and reopen the AI Agent to load the latest Skills

Important: Always use lark-cli update to update; it updates both the CLI and AI Skills.

Rule: Do not silently ignore update prompts. Even if the current task is unrelated to updates, inform the user after completing their request.

Security Rules

• Do not output secrets (appSecret, accessToken) in plain text to the terminal.
• Confirm user intent before write/delete operations.
• Use --dry-run to preview dangerous requests.
• File paths only accept relative paths: path parameters like --file, --output, --output-dir, @file only accept relative paths under cwd; absolute paths will result in unsafe file path. For data input (@file, large JSON), prefer stdin to avoid path and escaping issues.

High-Risk Operation Approval Protocol (exit 10)

lark-cli has a mandatory confirmation gate for high-risk write operations (risk: "high-risk-write"). When you call such a command without --yes, the CLI exits with code 10 and returns the following structured envelope on stderr:

{
  "ok": false,
  "error": {
    "type": "confirmation_required",
    "message": "drive +delete requires confirmation",
    "hint": "add --yes to confirm",
    "risk": {
      "level": "high-risk-write",
      "action": "drive +delete"
    }
  }
}

When this happens, do not treat it as a normal error and give up. Follow this process:

1. Identify: see subprocess exit code = 10 and stderr JSON error.type == "confirmation_required"
2. Confirm with user: show error.risk.action and key parameters to the user, explicitly state "this is a high-risk operation", and wait for explicit user consent
3. User agrees → append --yes to your original argv and retry
4. User refuses → terminate the flow, do not modify parameters or bypass the gate

Absolutely not allowed:

• Automatically add --yes and silently retry on exit 10 (this disables the gate)
• Treat confirmation_required as a network/permission error
• Append --yes and retry without explicit user consent
• Retry by shell-constructing the command with sh -c etc.—use exec.Command(argv...) parameter array form to avoid shell parsing treating user parameters as syntax

Proactive prediction: if you want the user to review the specific request of a dangerous operation first, add --dry-run when calling—it does not trigger the gate and prints the full request details (URL / body / params). You can show this preview to the user before actually executing.

How to Identify a High-Risk Command

• Shortcut: lark-cli <service> +<cmd> --help shows Risk: high-risk-write at the top
• Service command: lark-cli schema <service>.<resource>.<method> --format json returns "risk": "high-risk-write"