This skill guides you on how to operate Feishu resources through lark-cli, and what precautions to take.
Configuration initialization
First-time use requires running lark-cli config init to complete app configuration.
When you help the user initialize the configuration, use the background method to run the following command to start the app configuration process. After starting, read the output, extract the authorization link from it, and send it to the user:
# 发起配置（该命令会阻塞直到用户打开链接并完成操作或过期）
lark-cli config init --new
Authentication
Identity types
Two identity types, switched via --as :
| Identity | Identifier | How to obtain | Applicable scenarios |
|---|---|---|---|
| user user identity | --as user |
lark-cli auth login etc. |
Access the user's own resources (calendar, cloud space, etc.) |
| bot app identity | --as bot |
Automatic, only requires appId + appSecret | App-level operations, access the bot's own resources |
Identity selection principles
The output [identity: bot/user] represents the current identity. bot and user behave very differently, so you must confirm the identity matches the target requirement:
- Bot cannot see user resources: cannot access the user's calendar, cloud space documents, mailbox, and other personal resources. For example,
--as botquerying schedules returns the bot's own (empty) calendar - Bot cannot act on behalf of the user: messages are sent in the app's name, and created documents belong to the bot
- Bot permissions: only need to enable the scope in the Feishu developer console, no need for
auth login - User permissions: enable the scope in the console + the user authorizes via
auth login, both layers must be satisfied
Handling insufficient permissions
When encountering permission-related errors,adopt different solutions according to the current identity type。
The error response contains key information:
permission_violations: lists the missing scopes (choose 1 of N)console_url: the permission configuration link in the Feishu developer consolehint: the suggested fix command
Bot identity (--as bot）
Provide the console_url from the error to the user, and guide them to enable the scope in the console.Prohibitedto execute auth login。
User identity (--as user）
lark-cli auth login --domain <domain> # 按业务域授权
lark-cli auth login --scope "<missing_scope>" # 按具体 scope 授权（推荐,符合最小权限原则）
Rule: auth login must specify a scope (--domain or --scope). The scopes of multiple logins accumulate (incremental authorization).
Agent-initiated authentication (recommended)
When you, as an AI agent, need to help the user complete authentication, use the background method to execute the following command to start the authorization process, and send the authorization link to the user:
# 发起授权（阻塞直到用户授权完成或过期）
lark-cli auth login --scope "calendar:calendar:readonly"
Security rules
- Prohibited to output secrets(appSecret, accessToken) to the terminal in plaintext.
- Before write/delete operations, the user's intent must be confirmed。
- Use
--dry-runto preview dangerous requests.