lark-shared

Original：🇨🇳 Chinese
Translated

Lark CLI Shared Basics: Application configuration initialization, authentication login (auth login), identity switching (--as user/bot), permission and scope management, Permission denied error handling, and security rules. Triggered when users need to configure for the first time (`lark-cli config init`), use login authorization (`lark-cli auth login`), encounter insufficient permissions, switch user/bot identities, configure scope, or use lark-cli for the first time.

280.5kinstalls
Sourcelarksuite/cli
Added on

NPX Install

npx skill4agent add larksuite/cli lark-shared

Tags

Translated version includes tags in frontmatter
lark-cliconfiguration-managementauthenticationpermission-handlingsecurity-rules

SKILL.md Content (Chinese)

View Translation Comparison →

Lark CLI Shared Rules

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

Configuration Initialization

Run 
lark-cli config init
to complete application configuration for first-time use.
When helping users initialize configuration, use the background mode to initiate the application configuration process with the following command. After starting, read the output, extract the authorization link, and send it to the user:
bash
# 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, switchable via 
--as
:
IdentityIdentifierObtaining MethodApplicable Scenarios
User Identity
--as user
lark-cli auth login
, etc.		Access the user's own resources (calendar, cloud storage, etc.)
Bot Application Identity
--as bot
Automatic, only requires appId + appSecretApplication-level operations, access the bot's own resources

Identity Selection Principles

The output 
[identity: bot/user]
represents the current identity. Bot and user identities behave very differently, so ensure the identity meets the target requirements:
  • Bots cannot view user resources: Unable to access the user's calendar, cloud storage documents, email, and other personal resources. For example, querying schedules with 
    --as bot
    returns the bot's own (empty) calendar
  • Bots cannot operate on behalf of users: Messages are sent in the application's name, and created documents belong to the bot
  • Bot Permissions: Only need to enable scopes in the Lark Developer Backend, no 
    auth login
    required
  • User Permissions: Both enabling scopes in the backend and user authorization via 
    auth login
    are required

Handling Insufficient Permissions

When encountering permission-related errors, adopt different solutions based on the current identity type.
Error responses contain key information:
  • permission_violations
    : Lists missing scopes (choose one from N)
  • console_url
    : Link to permission configuration in the Lark Developer Backend
  • hint
    : Recommended fix command

Bot Identity (
--as bot
)

Provide the 
console_url
from the error to the user and guide them to enable the required scopes in the backend. Prohibit executing 
auth login
for bots.

User Identity (
--as user
)

bash
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 users complete authentication, use background mode to execute the following command to initiate the authorization process, and send the authorization link to the user:
bash
# Initiate authorization (blocks until the user completes authorization or it expires)
lark-cli auth login --scope "calendar:calendar:readonly"

Security Rules

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