lark-cli Sharing Rules

This skill guides you on how to operate Lark resources via lark-cli and highlights important considerations.

Configuration Initialization

For first-time use, you must run lark-cli config init to complete the application configuration.

When helping a user initialize the configuration, use the background method to initiate the configuration process with the command below. After starting, read the output, extract the authorization link, and send it to the user.

URL Forwarding Rules: When the command output contains URL fields such as verification_url, verification_uri_complete, or console_url: You must generate a QR code. You must 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 it. Prioritize generating a PNG QR code (--output); only use ASCII (--ascii) if the user explicitly requests it. URL Output Rules: Treat the URL as an immutable opaque string. Do not make any modifications (including URL encoding/decoding, adding spaces or punctuation, or reassembling the query). Display 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

There are two identity types, switchable via --as:

Identity Selection Principles

The output [identity: bot/user] represents the current identity. Bot and user behaviors differ significantly; ensure the identity matches the target requirement:

• Bot cannot see user resources: Cannot access personal resources such as the user's calendar, cloud space (drive/storage) documents, or email. For example, --as bot checking a schedule returns the bot's own (empty) calendar.
• Bot cannot act on behalf of the user: Messages are sent in the application's name, and created documents are owned by the bot.
• Bot permissions: Only need to enable scopes in the Lark Developer Console; auth login is not required.
• User permissions: Enable scopes in the console + user authorization via auth login; both layers must be satisfied.

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 1 of N)
• console_url: The permission configuration link in the Lark Developer Console
• hint: Suggested repair command

Bot Identity (--as bot)

Provide the console_url from the error to the user as-is, guiding them to the console to enable the scope. Do not perform 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 the principle of least privilege)

Rule: auth login must specify a scope (--domain or --scope). Scopes from multiple logins will accumulate (incremental authorization).

Agent-Initiated Authentication (Recommended)

When you, as an AI agent, need to help a user complete authentication, prioritize the split-flow to avoid blocking and waiting for user authorization within the same turn:

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

After obtaining the verification_url, send it to the user as-is as the final message of the current turn and end the turn/return control. Do not execute --device-code to block and poll immediately after displaying the URL in the same turn; in agent harnesses that do not pass through intermediate output, this will cause the user to never see the URL.

After the user replies that they have completed authorization, execute the following 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 the current turn, you must explicitly inform the user: "Please complete the authorization and let me know when you are done, and I will help you complete the subsequent steps."

Step 2: Complete Authorization (Subsequent Turn)

1. Wait for the user to reply "Authorization completed"
2. You (the AI agent) must personally execute: lark-cli auth login --device-code <device_code>
3. This command will poll the authorization status and complete the login
4. If authorization success is returned, the process is complete

Key Rules:

• You must personally execute the --device-code command; do not instruct the user to execute it themselves.
• Do not execute --device-code immediately after displaying the URL in the same turn; this will prevent the user from seeing the URL.
• Do not cache verification_url or device_code: Every time authorization is needed, you must re-execute lark-cli auth login --no-wait --json to generate a new link. Do not store authorization links or device codes in the context for reuse.

Update Checks

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

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

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

   lark-cli update
   

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

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

Rule: Do not silently ignore update prompts. Even if the current task is unrelated to the update, you should 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 such as --file, --output, --output-dir, and @file only accept relative paths under the cwd. Passing absolute paths will report unsafe file path. For data input (@file, large JSON), prioritize using stdin to avoid path and escaping issues.

Approval Protocol for High-Risk Operations (exit 10)

lark-cli has a mandatory confirmation gate for high-risk write operations (risk: "high-risk-write"). When you call such commands without --yes, the CLI will exit with code 10 and return the following structured envelope in 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 sub-process exit code = 10 and error.type == "confirmation_required" in the stderr JSON.
2. Confirm with the user: Display error.risk.action and key parameters to the user, explicitly state "This is a high-risk operation," and wait for the user's explicit consent.
3. User agrees → Retry by appending --yes to the end of your original argv.
4. User refuses → Terminate the process; do not rewrite parameters or skip the gate without authorization.

Absolutely forbidden:

• Defaulting to adding --yes and retrying silently when seeing exit 10 (this is equivalent to disabling the gate).
• Treating confirmation_required as a network or permission error.
• Appending --yes and retrying without the user's explicit consent.
• Using shell methods like sh -c to concatenate commands for retries, use the 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 for a dangerous operation first, call it with --dry-run, it does not trigger the gate and will print full request details (URL / body / params). You can show this preview to the user before executing it for real.

How to identify if a command is high-risk

• Shortcut: The top of lark-cli <service> +<cmd> --help will display Risk: high-risk-write.
• Service command: The return value of lark-cli schema <service>.<resource>.<method> --format json will contain "risk": "high-risk-write".