lark-cli sharing rules

This skill guides you on how to operate Lark resources using lark-cli and what precautions to take.

Configuration initialization

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

When you help a user initialize the configuration, use the background method to initiate the configuration application process with the following command. After starting, read the output, extract the authorization link from it, 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 forward the URL exactly as returned by the CLI to the user and treat it as an opaque string that cannot be modified. Do not perform URL encode/decode, do not add %20, spaces, or punctuation, do not reassemble the query, and do not rewrite it into Markdown link text. It is recommended to output it separately in a code block containing only the original URL.

# Initiate configuration (this command will block 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, which can be switched via --as:

Identity selection principles

The output [identity: bot/user] represents the current identity. The behavior of bot and user differs significantly, so you must confirm that the identity meets the target requirements:

• Bot cannot see user resources: Cannot access personal resources such as the user's calendar, cloud drive documents, or email. For example, --as bot to check the schedule returns the bot's own (empty) calendar.
• Bot cannot act on behalf of the user: Messages are sent in the name of the application, and created documents belong to the bot.
• Bot permissions: Only need to enable scope in the Lark developer console, no auth login required.
• User permissions: Enable scope 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 one 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, and guide them to the console to enable the scope. Do not perform auth login for the 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 using split-flow to avoid blocking and waiting for user authorization in the same turn:

# 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 to the user as the final message of the current turn as is, and end the turn/return control. Do not execute --device-code for blocking polling immediately after displaying the URL in the same turn; in an agent harness that does not pass through intermediate output, this will cause the user to never see the URL.

After the user replies that authorization is complete, execute the following in subsequent steps:

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

Update check

After a lark-cli command is executed, if a new version is detected, the JSON output will contain the _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 to execute the update (updating 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

• Prohibit outputting secrets (appSecret, accessToken) to the terminal in plain text.
• Must confirm user intent before write/delete operations.
• Use --dry-run to preview dangerous requests.

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 encountering this situation, do not give up as if it were a normal error. Handle it according to the following process:

1. Identify: See that the child 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, clearly 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 modify parameters or skip the gate without authorization.

Absolutely prohibited:

• Defaulting to adding --yes and retrying silently when seeing exit 10 (this is equivalent to disabling the gate).
• Treating confirmation_required as a network error 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 to let the user review the specific request for a dangerous operation first, add --dry-run when calling, 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: lark-cli <service> +<cmd> --help will display Risk: high-risk-write at the top.
• Service command: The return value of lark-cli schema <service>.<resource>.<method> --format json will contain "risk": "high-risk-write".