Lark Unified

Lark (飞书) is a comprehensive collaboration platform combining messaging, documents, spreadsheets, tables, calendars, and more. This skill provides unified access to the Lark CLI (lark-cli), a production-grade command-line tool with 200+ commands across 11 integrated business domains, along with 19 AI Agent-optimized skills.

⚠️ SETUP RULES — READ BEFORE DOING ANYTHING

FORBIDDEN — never run these commands under any circumstances:

• lark-cli config init --new
• lark-cli config init (interactive)
• lark-cli config set-default

These require a TTY, output a broken QR code in WorkBuddy, and must never be used.

REQUIRED setup procedure — follow exactly:

# Step 1: resolve or install lark-cli
LARK_CLI="$(command -v lark-cli || true)"
if [ -z "$LARK_CLI" ]; then
  env -u NODE_OPTIONS npm install -g @larksuite/cli
  LARK_CLI="$(command -v lark-cli || true)"
fi
if [ -z "$LARK_CLI" ]; then
  NPM_PREFIX="$(npm prefix -g 2>/dev/null || true)"
  LARK_CLI="$(find "$HOME/.npm-global/bin" "$NPM_PREFIX/bin" -name lark-cli -type f 2>/dev/null | head -1)"
fi
if [ -z "$LARK_CLI" ]; then
  echo "LARK_CLI_NOT_FOUND"
  exit 1
fi
"$LARK_CLI" --version

# Step 2: check if already configured (look for "appId" in output, NOT exit code)
"$LARK_CLI" config show 2>&1 | grep -q "appId" && echo "CONFIG_OK" || echo "NOT_CONFIGURED"

If step 2 prints NOT_CONFIGURED, run the setup script:

SETUP=$(find ~/.workbuddy/skills -name lark_setup.py 2>/dev/null | head -1)
LARK_CLI="$LARK_CLI" python3 "$SETUP"

# Lark (international) users:
LARK_CLI="$LARK_CLI" python3 "$SETUP" --brand lark

# If browser cannot open automatically:
# Print the URL clearly, ask the user to open it in a browser, and keep this command running while it polls.
LARK_CLI="$LARK_CLI" python3 "$SETUP" --no-browser

IMPORTANT: The setup script is a multi-step device flow.

• Step 1 (begin): The script requests a device code from Feishu. This call may return HTTP 400 transiently — this is normal, just retry.
• Step 2 (browser): The script opens a browser URL for the user to authorize.
• Step 3 (poll): The script polls until the user completes authorization in the browser. The poll API returns authorization_pending (as HTTP 400) while waiting — this is expected, NOT an error. Keep polling.
• Step 4 (save): Once authorized, the script saves the config.

If the setup script fails or you ran the begin step manually:

1. You already have the device_code — just keep polling with it until the user confirms in the browser.
2. Do NOT re-run the begin step unnecessarily. Reuse the existing device_code.
3. The authorization_pending response during polling is normal — it means the user hasn't finished yet. Wait and retry.

CRITICAL: App setup is not user OAuth. The setup script only creates/saves the app credentials. It does not guarantee the user is logged in. For personal data operations such as reading a user's accessible document, calendar, mail, task, or chat history, always check auth status first and complete user OAuth if needed.

First-use bootstrap — app setup + user OAuth must be chained

When the user asks for a personal-resource operation (for example reading a document URL, searching docs, checking calendar, mail, tasks, or chat history), the first-use flow MUST complete both stages before attempting the business API:

1. Resolve/install lark-cli using the setup procedure above.
2. Check app configuration with config show.
3. If app configuration is missing, run lark_setup.py and keep polling until it saves appId/appSecret.
4. Do not stop after app setup. Immediately run auth status.
5. If auth status reports no logged-in user, run user OAuth with recommended scopes.
6. Keep polling the same device_code until OAuth succeeds or expires.
7. Run auth status again and confirm identity is user and tokenStatus is valid or refreshable.
8. Only then retry the original user task once.

Tell the user the first-use flow may show two authorization pages:

第一次使用飞书套件需要完成两步连接：先初始化飞书 CLI 应用配置，再授权访问你有权限的飞书数据。两步完成后我会自动继续当前任务；这不是重复授权。

Use this exact command pattern after app setup succeeds:

# App setup may have just completed. Now continue with user OAuth; do not wait for another user prompt.
"$LARK_CLI" auth status
"$LARK_CLI" auth login --domain all --recommend --no-wait --json
"$LARK_CLI" auth login --device-code "<device_code>"
"$LARK_CLI" auth status

If the user OAuth device flow prints a verification_url, show that URL clearly and keep the polling command running. Do not start a new app setup or user OAuth flow while authorization_pending is still polling.

CRITICAL: polling timeout must outlive the device code. Device codes commonly expire after 10 minutes. When running lark_setup.py or lark-cli auth login --device-code, use a tool timeout longer than expires_in (recommended at least 700000 ms / 11+ minutes) or run the polling command in the background. If the polling command is interrupted by a tool timeout but the device code has not expired, reuse the same device_code and continue polling; do not start a new --no-wait or app setup flow. Only generate a new code after expired_token, invalid_grant, or a confirmed deadline expiry.

Fail-fast rules for auth and permission errors

Stop retrying business APIs when any of these errors appears. Do not switch identities or change unrelated flags repeatedly.

Error signal	Meaning	Required action
need_user_authorization / No user logged in / failed to get access token	User OAuth is missing or expired	Stop API retries. Run user device-flow login, show the verification URL clearly, keep polling with the same device_code, then rerun auth status.
forBidden / forbidden with --as bot	The bot/app is not authorized for the target resource, commonly because it is not a document collaborator	Stop bot retries. Use --as user after user OAuth, or ask the user to add the bot/app as a collaborator to the document/resource.
App scope not enabled / required scope ...	The current app has not enabled the required Open Platform scope; user OAuth alone cannot grant it	Stop retries. Tell the user/admin which scope must be enabled in the Feishu developer console, then retry after the app scope is enabled and OAuth includes it.
authorization_pending	The user has not finished the browser authorization yet	Keep the existing polling command running. Do not start a new setup/login flow unless the device code expires.
expired_token / invalid_grant	The device code expired	Start exactly one new login/setup flow and give the user the new URL.

Retry budget: after one failed business API call with an auth/permission error, diagnose and switch to the required auth step. Never perform repeated API attempts with --as user, --as bot, --format, or unrelated command variants.

Getting Started

# Verify app setup is complete
"$LARK_CLI" config show

# Verify user authorization status
"$LARK_CLI" auth status

If auth status reports no logged-in user and personal operations are needed, run the recommended-scope login. Before starting, tell the user clearly:

本次将连接飞书并授权推荐权限范围，覆盖多数常见飞书操作。由于飞书权限按能力拆分，后续执行文档搜索、云盘检索、导出等更具体操作时，仍可能需要补充授权；补充授权不是重新连接，而是为当前新增能力追加 scope。

# Start user device-flow login for recommended scopes across domains
"$LARK_CLI" auth login --domain all --recommend --no-wait --json

# Tell the user: "请复制并打开 verification_url，在浏览器里完成飞书授权。"
# Then keep polling with the returned device_code until success or timeout.
"$LARK_CLI" auth login --device-code "<device_code>"

# Verify tokenStatus is valid and identity is user before reading personal resources
"$LARK_CLI" auth status

When additional scopes are needed: --scope cannot be combined with --domain or --recommend. Do not replace recommended login with a tiny explicit scope set unless you are intentionally narrowing the token. For a supplemental authorization, explain the exact missing capability and scope to the user, for example:

当前任务需要补充授权：飞书文档搜索权限 search:docs:read。授权后，后续搜索飞书文档不会再次要求这个权限。

Then run an explicit-scope login for the missing scope or for a maintained capability bundle, and verify with auth status before retrying the business API once.

All commands:

lark-cli <domain> <resource> <method> [flags]
lark-cli <domain> +<shortcut> [flags]  # shortcuts preferred

Default identity: --as auto. It uses the logged-in user when available and falls back to bot identity when no user is logged in. For personal resources (docs the user can open, calendar, mail, tasks, chat history), prefer --as user after auth status is valid. Use --as bot only for app/bot operations or resources where the bot is explicitly a member/collaborator.

Document creation identity rules

• Default to --as user for user-requested docs/sheets so the user owns them.
• Use --as bot only when the user explicitly asks for bot/app-owned content.
• If a bot-created doc must be shared, add user permission; this requires docs:permission.member:create. If that scope is not enabled, stop and ask an admin to enable it.

Core Capability Domains

Lark has 11 primary business domains. Each has dozens of commands, with high-level shortcuts for common operations:

✉️ Instant Messaging (lark-im)

Send/receive messages, search chat history, manage groups, download files, and manage reactions.

Common shortcuts: +messages-send, +messages-search, +chat-messages-list, +chat-create

Use when: Messaging users, retrieving conversations, building chat-based workflows, downloading attachments

→ For detailed API reference, shortcuts, and permission requirements: See references/lark-im.md

📄 Cloud Documents (lark-doc)

Create and edit documents, insert media, manage document permissions, and link to wikis.

Common shortcuts: +documents-create, +documents-list

Use when: Creating documents programmatically, building document workflows, embedding content

→ For full reference: See references/lark-doc.md

💾 Cloud Drive & Files (lark-drive)

Upload/download files, manage file permissions, share links, and add comments on files.

Common shortcuts: +files-upload, +files-download

Use when: Managing file storage, automating uploads/downloads, sharing files

→ For full reference: See references/lark-drive.md

📊 Spreadsheets (lark-sheets)

Read/write/append to spreadsheets, query data, and manage sheet permissions.

Common shortcuts: +spreadsheets-read, +spreadsheets-append, +spreadsheets-find

Use when: Automating spreadsheet operations, reading/updating sheet data, building data workflows

→ For full reference: See references/lark-sheets.md

🗂️ Base & Multi-Dimensional Tables (lark-base)

Query and manage multi-dimensional table records, fields, views, dashboards, and run workflows.

Common shortcuts: +tables-records-list, +tables-records-create, +fields-list

Use when: Managing relational data, querying tables, automating base operations, triggering workflows

→ For full reference: See references/lark-base.md

📅 Calendar (lark-calendar)

Query events, check availability, suggest meeting times, and manage calendar settings.

Common shortcuts: +calendars-list, +events-list, +events-search-freebusy

Use when: Checking schedules, coordinating meetings, finding available time slots

→ For full reference: See references/lark-calendar.md

📋 Tasks & To-Do (lark-task)

Create tasks, organize into lists, manage reminders, and track subtasks.

Common shortcuts: +tasks-create, +tasks-list, +task-lists-list

Use when: Creating tasks, building task workflows, managing team task lists

→ For full reference: See references/lark-task.md

📧 Mail (lark-mail)

Compose emails, manage drafts, search messages, reply/forward, and send emails.

Common shortcuts: +messages-send, +messages-search, +drafts-create

Use when: Building email workflows, automating mail operations, searching email history

→ For full reference: See references/lark-mail.md

📚 Wiki & Knowledge Spaces (lark-wiki)

Create knowledge spaces, organize pages into hierarchies, and manage wiki permissions.

Common shortcuts: +spaces-create, +wiki-pages-create, +wiki-pages-list

Use when: Building knowledge bases, organizing documentation, creating wikis

→ For full reference: See references/lark-wiki.md

🎥 Video Conference & Meetings (lark-vc)

Search meeting recordings, retrieve meeting notes, and manage VC settings.

Use when: Accessing meeting data, retrieving recordings and notes, managing video settings

→ For full reference: See references/lark-vc.md

👥 Contacts & Directory (lark-contact)

Search users, fetch contact profiles, and query user directory.

Use when: Searching for users, building user lookups, retrieving contact information

→ For full reference: See references/lark-contact.md

Core Concepts & Common Patterns

Identity & Authentication

• User identity (--as user): Operations run as the authenticated user. Uses user_access_token. Permissions depend on the user's own access.
• Bot identity (--as bot): Operations run as the app's bot. Uses tenant_access_token. Permissions depend on the bot's scopes and membership.

Most APIs support both modes, but behavior differs based on the caller's role and access.

Common Entity IDs

• User: open_id, user_id, email
• Chat: chat_id (oc_xxx)
• Message: message_id (om_xxx)
• Thread: thread_id
• Document: document_id
• File: file_key or file_id
• Table/Base: base_id, table_id
• Event: event_id

Working with the CLI

Using Shortcuts (Recommended)

Shortcuts are high-level wrappers around common operations. Always use shortcuts when available:

lark-cli im +messages-send --chat-id oc_xxx --text "Hello"
lark-cli sheets +spreadsheets-read --spreadsheet-id spr_xxx

Using Raw APIs

For operations without shortcuts, use raw API commands with schema inspection:

lark-cli schema im.messages.create       # View parameter structure
lark-cli im messages create --data '{...}'  # Call with structured data

Important: Always run schema before calling raw APIs to understand the exact parameter format.

Pagination & Filtering

Most list operations support:

• --limit: Number of records to return (default varies by API)
• --offset / --page-token: Pagination cursor
• --filter: Server-side filtering (format varies by resource)

Output Formatting

By default, commands return JSON. Common options:

• --table: Format output as ASCII table
• --csv: Export as CSV
• --yaml: YAML format
• --raw: Unformatted raw output

Workflows

Lark offers two built-in workflow skills:

• Meeting Summary Workflow (lark-workflow-meeting-summary): Aggregate meeting notes
• Standup Report Workflow (lark-workflow-standup-report): Generate daily standup summaries

See references/workflows.md for details.

Advanced Features

Custom Skills & Integrations

Use lark-skill-maker to create custom skills by wrapping Lark APIs. See references/skill-maker.md.

OpenAPI Discovery

Use lark-openapi-explorer to discover and test Lark APIs directly. See references/openapi.md.

Event Subscriptions

Subscribe to real-time events via WebSocket with lark-event. See references/events.md.

Other Domains

• Minutes: Meeting minutes metadata (lark-minutes)
• Whiteboard: Drawing/diagram creation with DSL (lark-whiteboard)
• Shared: Core authentication rules and identity management (lark-shared)

See references/other-domains.md for details.

Quick Example

Send a message to a chat

# First, find the chat
lark-cli im +chat-search --keyword "engineering"

# Then send a message
lark-cli im +messages-send --chat-id oc_xxx --text "Hello team!"

Search past messages

lark-cli im +messages-search --query "deadline" --from-user ou_xxx --start-time 2024-01-01 --end-time 2024-01-31

Create a spreadsheet and add data

lark-cli sheets +spreadsheets-create --title "Q1 Data"
lark-cli sheets +spreadsheets-append --spreadsheet-id spr_xxx --range "Sheet1!A1" --values "[[1,2,3]]"

Query a base table

lark-cli base +tables-records-list --base-id app_xxx --table-id tbl_xxx --limit 100

Need Help?

• View all domains: lark-cli --help
• Domain-specific help: lark-cli <domain> --help
• Inspect API schema: lark-cli schema <domain>.<resource>.<method>
• Permission requirements: Check the permission tables in each domain's reference file

Next Steps

1. Choose your domain from the list above
2. Read the domain reference (linked in each section)
3. Use shortcuts for common operations
4. Inspect schemas if using raw APIs
5. Check permissions in the reference documentation