Lark Unified

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: install lark-cli if missing
lark-cli --version 2>/dev/null || npm install -g @larksuite/cli

# Step 2: check if already configured (look for "app_id" in output, NOT exit code)
lark-cli config show 2>&1 | grep -q "app_id" && 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)
python3 "$SETUP"

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

# If browser cannot open automatically:
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.

Getting Started

# Verify setup is complete
lark-cli config view

All commands:

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

Default identity: --as bot. Use --as user for personal operations.

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

Reference Documentation for Lark Unified

This is a placeholder for detailed reference documentation. Replace with actual reference content or delete if not needed.

Example real reference docs from other skills:

• product-management/references/communication.md - Comprehensive guide for status updates
• product-management/references/context_building.md - Deep-dive on gathering context
• bigquery/references/ - API references and query examples

When Reference Docs Are Useful

Reference docs are ideal for:

• Comprehensive API documentation
• Detailed workflow guides
• Complex multi-step processes
• Information too lengthy for main SKILL.md
• Content that's only needed for specific use cases

Structure Suggestions

API Reference Example

• Overview
• Authentication
• Endpoints with examples
• Error codes
• Rate limits

Workflow Guide Example

• Prerequisites
• Step-by-step instructions
• Common patterns
• Troubleshooting
• Best practices

Lark-Base - Multi-Dimensional Tables

Important: Read lark-shared reference first for authentication and permission basics.

Core Concepts

• Base: Container for tables (base_id: app_xxx)
• Table: Data table within base (table_id: tbl_xxx)
• Field: Column definition (field_id: fld_xxx) — text, number, select, date, lookup, formula, etc.
• Record: Row in table (record_id: rec_xxx)
• View: Saved query/filter on table (view_id: vew_xxx)
• Workflow: Automation rules in table

Resource Hierarchy

Base (app_xxx)
├── Table (tbl_xxx)
│   ├── Field (fld_xxx)
│   │   ├── Property (field type, formula, lookup)
│   │   └── Permission
│   ├── Record (rec_xxx)
│   │   ├── Field value
│   │   └── Link to other records
│   ├── View (vew_xxx)
│   │   ├── Filter
│   │   ├── Sort
│   │   └── Group
│   └── Form/Dashboard/Workflow
└── Role/Automation/Notification

Common Shortcuts

Typical Workflow

1. List bases: lark-cli base bases list 2. List tables: lark-cli base tables list --base-id app_xxx 3. Get fields: lark-cli base +fields-list --base-id app_xxx --table-id tbl_xxx 4. Query records: lark-cli base +tables-records-list --base-id app_xxx --table-id tbl_xxx --limit 100 5. Filter & sort: lark-cli base +tables-records-list --base-id app_xxx --table-id tbl_xxx --filter "[condition]" --sort "[sort_spec]" 6. Create record: lark-cli base +tables-records-create --base-id app_xxx --table-id tbl_xxx --data '{"field_id":"value"}' 7. Update record: lark-cli base tables records update --base-id app_xxx --table-id tbl_xxx --record-id rec_xxx --data '{...}'

Field Types

• Text, Long Text, Email, URL, Phone
• Number (integer, decimal)
• Select (single/multi), Tag
• Date, Time, Datetime
• Checkbox, Rating, Progress
• User, Department, Lookup, Link
• Formula, Rollup, Count
• Attachment, Custom Fields

API Resources

bases

• list — List all accessible bases
• get_meta — Get base metadata

tables

• list — List tables in base
• get_meta — Get table metadata
• create — Create new table
• delete — Delete table

fields

• list — List fields in table
• get — Get field definition
• create — Create field
• update — Update field
• delete — Delete field

records

• list — List records (supports filter, sort, pagination)
• search — Search records
• create — Create record
• update — Update record
• batch_update — Batch update records
• delete — Delete record
• batch_delete — Batch delete records

views

• list — List views in table
• get_meta — Get view metadata
• query — Query view data

dashboards

• list — List dashboards
• get_meta — Get dashboard metadata

workflows

• list — List automation workflows
• trigger — Manually trigger workflow

Permission Table

Lark-Calendar - Scheduling & Events

Important: Read lark-shared reference first for authentication and permission basics.

Core Concepts

• Calendar: Personal or shared calendar
• Event: Meeting or appointment with attendees
• Freebusy: Busy/available time slots for user
• Attendee: Participant in event (RSVP status: accept, decline, tentative, no_reply)
• Organizer: Creator/owner of event

Common Scenarios

1. Book an Event

lark-cli calendar +create --user ou_xxx --title "Team Sync" --start-time 2024-02-15T10:00:00 --end-time 2024-02-15T11:00:00 --attendees "user1@example.com" "user2@example.com"

2. Check Availability

lark-cli calendar +freebusy --user ou_xxx --start-time 2024-02-15T08:00:00 --end-time 2024-02-15T18:00:00

3. Suggest Meeting Times

lark-cli calendar +suggestion --user ou_xxx --duration 60 --start-time 2024-02-15 --end-time 2024-02-20 --attendees "user1@example.com" "user2@example.com"

4. View Today's Agenda

lark-cli calendar +agenda

Common Shortcuts

API Resources

calendars

• list — List user's calendars
• get — Get calendar details

events

• create — Create event
• list — List events in calendar
• search — Search events
• update — Update event
• delete — Delete event
• get — Get event details

freebusy

• query — Query user's free/busy times and RSVP status

calendars.events.attendees

• create — Add attendee to event
• delete — Remove attendee

Permission Table

Lark-Doc - Cloud Documents

Important: Read lark-shared reference first for authentication and permission basics.

Core Concepts

Document Types & Tokens

Different document types have different URL formats and token handling:

Wiki Link Special Handling (Important!)

Wiki links may point to different document types (docx, doc, sheet, bitable, slides, file, mindnote). Cannot assume URL token is file_token.

Processing flow: 1. Query node: lark-cli wiki spaces get_node --params '{"token":"wiki_token"}' 2. Extract from response: node.obj_type (document type) and node.obj_token (real token) 3. Use appropriate API based on obj_type

Common Shortcuts

API Resources

docs

• create — Create document
• get — Get document content
• list — List user documents
• update — Update document
• delete — Delete document
• raw_content — Get raw document content

docx

• document.blocks.* — Manage document blocks
• document.children.* — Manage child elements

drive (file operations)

• file.comments.* — Manage document comments

Permission Table

Lark-Drive - Cloud Storage & Files

Important: Read lark-shared reference first for authentication and permission basics.

Core Concepts

• Folder: Directory in cloud storage (folder_token: fldcn_xxx)
• File: Document or attachment (file_token, file_key, file_id)
• Permission: Access level (viewer, editor, owner)
• Comment: Annotation on file

Resource Hierarchy

Folder (folder_token)
└── File (file_token)
    ├── Comment (comment_id)
    ├── Permission (user_id, role)
    └── Resource (attachment/version)

Common Shortcuts

Typical Workflow

1. List files: lark-cli drive +files-list --folder-token fldcn_xxx 2. Upload file: lark-cli drive +files-upload --folder-token fldcn_xxx --local-path "./data.csv" 3. Download file: lark-cli drive +files-download --file-token xxxxx --local-path "./output/" 4. Get permissions: lark-cli drive files permissions get --file-token xxxxx 5. Share file: lark-cli drive files copy --file-token xxxxx

API Resources

files

• get_meta — Get file metadata
• copy — Copy file
• delete — Delete file
• download — Download file content
• upload — Upload file
• task_check — Check async task status

files.permissions

• get — Get file permissions
• batch_get — Batch get permissions
• create — Grant permission
• update — Update permission
• delete — Revoke permission

files.comments

• create — Add comment on file
• get — Get comment
• list — List comments
• update — Update comment
• delete — Delete comment

folders

• create — Create folder
• get_meta — Get folder metadata
• list_children — List folder contents
• delete — Delete folder
• copy — Copy folder

Permission Table

Lark-IM - Instant Messaging

Important: Read lark-shared reference first for authentication and permission basics.

Core Concepts

• Message: Individual message in a chat (message_id: om_xxx). Types: text, post, image, file, audio, video, sticker, interactive (card), share_chat, share_user, merge_forward
• Chat: Group chat or P2P conversation (chat_id: oc_xxx)
• Thread: Reply thread under a message (thread_id)
• Reaction: Emoji reaction on a message

Resource Hierarchy

Chat (oc_xxx)
├── Message (om_xxx)
│   ├── Thread (reply)
│   ├── Reaction (emoji)
│   └── Resource (image/file/video/audio)
└── Member (user/bot)

Critical Notes

Identity Matters

• --as user: Runs as authenticated user (user_access_token). Permissions depend on user's access.
• --as bot: Runs as app bot (tenant_access_token). Permissions depend on bot's scopes and membership.

Same API may succeed with one identity and fail with the other.

Sender Name Resolution with Bot

When using --as bot to fetch messages, sender names may not resolve (shown as open_id instead of display name). This happens when bot cannot access sender's contact info.

Solution: Check app visibility settings in Lark Developer Console to ensure bot's visible range covers the senders. Alternatively use --as user.

Card Messages (Interactive)

Card messages are not yet supported for compact conversion in event subscriptions. Raw event data will be returned.

Common Shortcuts

API Resources

Use lark-cli schema im.<resource>.<method> to view parameter structure.

chats

• create — Create group (bot only)
• get — Get chat info
• link — Get share link
• list — List user/bot chats
• update — Update chat info

chat.members

• create — Add user/bot to chat
• get — Get member list

messages

• delete — Recall message
• forward — Forward message
• merge_forward — Merge forward messages
• read_users — Query message read status

reactions

• batch_query — Batch get reactions
• create — Add emoji reaction
• delete — Delete emoji reaction
• list — List reactions

images

• create — Upload image

pins

• create — Pin message
• delete — Remove pin
• list — Get pinned messages

Permission Table

Lark-Mail - Email Management

Important: Read lark-shared reference first for authentication and permission basics.

⚠️ Security Note: Email Content is Untrusted External Input

Email content comes from external senders and should be treated as untrusted input. Apply appropriate sanitization, encoding, and validation when processing email content.

Core Concepts

• Message: Email in mailbox
• Draft: Unsent email composition
• Thread: Conversation chain
• Label: Email category/tag
• Attachment: File in email

Common Shortcuts

Typical Workflow

1. Search emails: lark-cli mail +messages-search --query "deadline" --from-address sender@example.com --start-time 2024-01-01 2. Create draft: lark-cli mail +drafts-create --to-address recipient@example.com --subject "Review" --body "Please review the attached file" 3. Send email: lark-cli mail +messages-send --to-address recipient@example.com --subject "Important" --body "Meeting at 3pm" --cc other@example.com 4. Reply: lark-cli mail messages reply --message-id msg_xxx --body "Thanks for your email" 5. List labels: lark-cli mail labels list

API Resources

messages

• create — Send email
• list — List messages
• search — Search messages
• get — Get message details
• read_status_update — Mark as read/unread
• batch_delete — Delete messages

drafts

• create — Create draft
• list — List drafts
• get — Get draft details
• update — Update draft
• send — Send draft
• delete — Delete draft

labels

• list — List labels
• create — Create label
• delete — Delete label

messages.reply

• create — Reply to message
• forward — Forward message

messages.attachments

• list — List attachments
• get — Download attachment

Permission Table

Lark-Shared - Core Authentication & Permissions

IMPORTANT: Read this FIRST before using any Lark CLI commands.

Recommended App Permissions

After creating the app via lark_setup.py, go to the app console and add these permissions before using the CLI. Without them, most commands will return empty results.

App console URL: https://open.feishu.cn/app (find your App ID with lark-cli config show)

Core permissions (add all of these)

After adding permissions: publish a new version in the app console, then re-run the setup script to get a fresh token with the new scopes:

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

Quick Start: Configure Credentials

Check if config already exists:

lark-cli config view

If not configured, use the inline setup script from SKILL.md (no TTY required).

NEVER use `lark-cli config init` or `lark-cli config init --new` directly — these require an interactive TTY and will display a broken QR code or hang in WorkBuddy.

Manual alternative (if you already have an App ID and App Secret):

echo "<APP_SECRET>" | lark-cli config init --app-id <APP_ID> --app-secret-stdin

Platforms:

• Feishu (China): https://open.feishu.cn
• Lark (International): https://open.larksuite.com

Other config commands:

lark-cli config view                    # View current configuration
lark-cli config use-config <name>       # Switch between configurations

Identity: User vs Bot

Every Lark CLI operation runs with one of two identities:

User Identity (--as user)

• Token: user_access_token
• Permissions: Based on the authenticated user's own access
• Scope: Personal scopes (what the user can do)
• Usage: lark-cli <domain> <resource> <method> --as user ...
• When to use:
• User is performing personal actions (send message, check calendar)
• Need to respect user's own access boundaries
• Searching personal content (messages, documents, calendar)

Bot Identity (--as bot)

• Token: tenant_access_token
• Permissions: Based on app's scopes + bot's membership/configuration
• Scope: App-level scopes (what the bot can do)
• Usage: lark-cli <domain> <resource> <method> --as bot ...
• When to use:
• App/bot is performing actions (send message to others, create group)
• Need to use app's elevated permissions
• Bot has special roles (group owner, admin, etc.)

Same API, Different Behavior

The same API may succeed or fail depending on identity:

# May work: User sending message to own chat
lark-cli im messages.get --message-id om_xxx --as user

# May fail: User lacks permission
lark-cli im messages.get --message-id om_xxx --as user  # If user not in chat

# May work: Bot has broader access
lark-cli im messages.get --message-id om_xxx --as bot  # If bot in chat

Scopes: Permission Model

Operations require specific OAuth scopes. Each scope grants specific capabilities:

Common Scopes

Messaging: im:chat:read, im:chat:write, im:message, im:message:recall

Documents: docs:document:read, docs:document:edit, docs:document:create

Spreadsheets: sheets:spreadsheet:read, sheets:spreadsheet:edit

Base: bitable:base:read, bitable:base:edit

Calendar: calendar:calendar:read, calendar:event:create

Tasks: task:task:read, task:task:create

Mail: mail:message:read, mail:message:write

Wiki: wiki:space:read, wiki:space:create

Drive: drive:file:read, drive:file:write

Check each domain's reference file for complete scope requirements.

Configuration Files

Lark CLI stores configuration in ~/.lark/config.toml:

[default]
tenant_key = "xxxxxxx"
app_id = "xxxxxxx"
app_secret = "xxxxxxx"

[dev]
tenant_key = "yyyyyyy"
app_id = "yyyyyyy"
app_secret = "yyyyyyy"

Switch between configs: lark-cli config use-config dev

Permission Errors

If an operation fails with a permission error:

1. Check identity: Is it using --as user or --as bot? 2. Check scopes: Does the app have the required OAuth scopes? 3. Check membership: Is the user/bot in the target group/chat? 4. Check role: Does the user/bot have required role (owner, admin, etc.)?

Example: Message Not Found

Error: message not found

Possible causes:
1. Message was deleted
2. User/bot not in the chat containing the message
3. Message is older than API retention period (usually 7 days for some operations)
4. Insufficient scopes

Common Permission Issues

Sender Name Not Resolving

When using bot identity and sender name shows as open_id instead of display name:

• Root cause: Bot cannot access sender's contact info
• Solution: Check app visibility in Developer Console. Ensure bot's visible range includes the senders.
• Alternative: Use --as user instead, which typically has broader contact access

Chat Not Found

• User identity: User must be a member of the chat
• Bot identity: Bot must be a member AND within app's availability range

Cannot Create Group

• Bot only: User identity cannot create groups
• Use: --as bot with im:chat:create scope

Testing Permissions

# Check current credential status
lark-cli config view

# Test a simple operation (list chats)
lark-cli im chats list --as user

# If this fails, check:
# 1. Configuration is correct: lark-cli config view
# 2. Token is valid (might be expired)
# 3. Scopes include im:chat:read

# Re-authenticate if needed
lark-cli config set-default

Security Best Practices

1. Keep tokens private: Never commit credentials to version control 2. Use environment variables for automation:

   export LARK_TENANT_KEY="xxxxx"
   export LARK_APP_ID="xxxxx"
   export LARK_APP_SECRET="xxxxx"
   lark-cli config import-env

3. Minimize scopes: Only request scopes your app actually needs 4. Rotate credentials: Periodically rotate app secrets 5. Validate untrusted input: Email content, user input, etc. can be malicious

More Help

lark-cli config --help
lark-cli --version

Lark-Sheets - Spreadsheets

Important: Read lark-shared reference first for authentication and permission basics.

Core Concepts

• Spreadsheet: Container for sheets (spreadsheet_id: spr_xxx)
• Sheet: Individual worksheet within spreadsheet (sheet_id, sheet_name)
• Range: Cell range in A1 notation (e.g., "Sheet1!A1:C10")
• Cell: Individual cell with value (row, col)

Common Shortcuts

Typical Workflow

1. Create spreadsheet: lark-cli sheets +spreadsheets-create --title "Data" 2. Write header row: lark-cli sheets +spreadsheets-append --spreadsheet-id spr_xxx --range "Sheet1!A1" --values "[[Header1,Header2,Header3]]" 3. Append data: lark-cli sheets +spreadsheets-append --spreadsheet-id spr_xxx --values "[[1,2,3],[4,5,6]]" 4. Read data: lark-cli sheets +spreadsheets-read --spreadsheet-id spr_xxx --range "Sheet1!A1:C100" 5. Find values: lark-cli sheets +spreadsheets-find --spreadsheet-id spr_xxx --find "SearchTerm"

API Resources

spreadsheets

• create — Create spreadsheet
• query — Get spreadsheet metadata
• batch_query — Batch get spreadsheets
• update — Update spreadsheet properties

spreadsheets.sheets

• query — Get sheet properties
• batch_query — Batch get sheet info

spreadsheets.values

• get — Read cell range
• batch_get — Batch read ranges
• update — Update cell range
• batch_update — Batch update ranges
• append — Append rows
• clear — Clear range

spreadsheets.finds

• find — Find cells by value
• batch_find — Batch find operations

Permission Table

Lark-Task - Tasks & To-Do Lists

Important: Read lark-shared reference first for authentication and permission basics.

Core Concepts

• Task: Individual to-do item
• Task List: Collection of tasks
• Subtask: Task nested under parent task
• Assignee: User assigned to task
• Milestone: Deadline or target date
• Priority: Task importance level (low, medium, high, urgent)

Common Shortcuts

Typical Workflow

1. View my tasks: lark-cli task +tasks-list --assignee me --status active 2. Create task: lark-cli task +tasks-create --title "Review PR #123" --due-date 2024-02-15 3. Assign task: lark-cli task tasks update --task-id task_xxx --assignee ou_yyy 4. Mark complete: lark-cli task tasks update --task-id task_xxx --status completed 5. Create subtask: lark-cli task subtasks create --task-id task_xxx --title "Subtask"

API Resources

tasks

• create — Create task
• list — List tasks
• get — Get task details
• update — Update task (title, status, assignee, etc.)
• delete — Delete task

task_lists

• create — Create task list
• list — List task lists
• get — Get list details
• update — Update list name/description
• delete — Delete list

subtasks

• create — Create subtask
• list — List subtasks
• update — Update subtask
• delete — Delete subtask

tasks.collaborators

• create — Add collaborator to task
• list — List task collaborators
• delete — Remove collaborator

Status Values

• active
• completed
• archived
• cancelled

Permission Table

Lark-Wiki - Knowledge Spaces & Documentation

Important: Read lark-shared reference first for authentication and permission basics.

Core Concepts

• Space: Knowledge space container (space_id)
• Node: Document/page in space (wiki_token, obj_token)
• Hierarchy: Nested page structure
• Shortcut: Quick link to document in space
• obj_type: Type of node (docx, doc, sheet, bitable, slides, file, mindnote)

Resource Hierarchy

Space (space_id)
└── Node (wiki_token)
    ├── obj_type: docx (cloud document)
    ├── obj_type: sheet (spreadsheet)
    ├── obj_type: bitable (multi-dimensional table)
    ├── obj_type: slides (presentation)
    ├── obj_type: file (regular file)
    └── Child nodes (nested)

Important Note: Wiki Links Require Resolution

Wiki links (wiki_token) cannot be used directly. Must query to get the actual object type and token:

lark-cli wiki spaces get_node --params '{"token":"wiki_token"}'
# Returns: obj_type, obj_token, title

Then use appropriate API based on obj_type (docs, sheets, bitable, drive, etc.).

Common Shortcuts

Typical Workflow

1. List spaces: lark-cli wiki spaces list 2. Get space details: lark-cli wiki spaces get_meta --space-id space_xxx 3. List nodes: lark-cli wiki spaces list_nodes --space-id space_xxx 4. Query wiki link: lark-cli wiki spaces get_node --params '{"token":"wiki_token"}' 5. Create page: lark-cli wiki spaces create_node --space-id space_xxx --title "New Page" --parent-node-token xxx 6. Move node: lark-cli wiki spaces move_node --wiki-token xxx --parent-node-token new_parent_xxx

API Resources

spaces

• list — List knowledge spaces
• get_meta — Get space metadata
• list_nodes — List nodes in space
• get_node — Get node info (critical: resolves wiki_token to obj_token)
• create_node — Create page in space
• update_node — Update node properties
• delete_node — Delete node
• move_node — Move node to different parent
• copy_node — Copy node to different parent

spaces.members

• create — Add member to space
• list — List space members
• delete — Remove member

Permission Table

Additional Lark Domains

Lark-Contact - Contacts & User Directory

When to use: Search for users, fetch user profiles, query organizational structure.

Common Shortcuts

Typical Operations

# Get current user info
lark-cli contact +me

# Search users
lark-cli contact +users-search --query "John" --limit 20

# Get department structure
lark-cli contact departments list

Key Resources

• user.get — Get user profile
• user.list — List users
• user.search — Search users
• department.list — List departments
• department.get — Get department info

---

Lark-VC - Video Conferences & Meetings

When to use: Access meeting recordings, retrieve meeting notes, manage video conference settings.

Common Scenarios

1. Search past meetings: Find meetings from last week 2. Get meeting notes: Retrieve automated summaries, action items, or transcripts 3. Download recordings: Access meeting video recordings

Typical Operations

# Search meetings from past week
lark-cli vc +meetings-search --from-user ou_xxx --start-time 2024-02-08 --end-time 2024-02-15 --limit 100

# Get meeting minutes/notes
lark-cli vc minutes get --meeting-id vc_xxx

# Get meeting recording
lark-cli vc recordings get --meeting-id vc_xxx

Key Resources

• meetings.list — List meetings
• meetings.search — Search meetings by organizer/attendee/time
• meetings.get — Get meeting details
• minutes.get — Get meeting notes/summary
• recordings.list — List recordings
• recordings.get — Get recording details

Note on Freebusy vs Meetings

• Use lark-calendar for future events and scheduling
• Use lark-vc for past meetings, recordings, and notes

---

Lark-Minutes - Meeting Minutes

When to use: Retrieve meeting minutes metadata and associated content.

Typical Operations

lark-cli minutes minutes-list --meeting-id vc_xxx
lark-cli minutes minutes-get --minutes-id minutes_xxx

---

Lark-Whiteboard - Drawing & Diagrams

When to use: Create or manage diagrams using DSL (Domain Specific Language).

Rendering

Supports Mermaid syntax for flowcharts, sequence diagrams, state machines, etc.

Typical Operations

# Create whiteboard with Mermaid diagram
lark-cli whiteboard create --title "Architecture Diagram" --content "graph LR; A[Start] --> B[Process] --> C[End]"

---

Lark-Event - Real-Time Event Subscriptions

When to use: Subscribe to real-time events (messages, document changes, base updates) via WebSocket.

Usage Pattern

# Subscribe to message events
lark-cli event subscribe --event-type message.receive --endpoint wss://your-endpoint

Supported Events

• Messages: create, update, delete
• Documents: updated
• Base: record created/updated/deleted
• Calendar: event changes
• And many more...

---

Lark-Shared - Core Authentication & Configuration

Always read this first before using any other Lark skill.

Key Concepts

• Identity: User vs Bot
• Token Types: user_access_token vs tenant_access_token
• Scopes: Permissions required for each operation
• Configuration: How to set up credentials

Critical Notes

• User operations (--as user): Use user's permissions
• Bot operations (--as bot): Use bot's app scopes and membership
• Some APIs support only one identity type
• Always check the reference for identity requirements

---

Lark-OpenAPI-Explorer - API Discovery

When to use: Discover and test Lark APIs directly, explore API schemas.

Usage

lark-cli openapi search --query "message"  # Search available APIs
lark-cli openapi get --api im.messages.send  # Get API details

---

Lark-Skill-Maker - Create Custom Skills

When to use: Build custom skills by wrapping Lark APIs for specialized workflows.

Typical Usage

Skill-maker allows you to:

• Define custom commands
• Wrap complex API sequences
• Add business logic
• Export as reusable skills

See official documentation for detailed skill authoring guidelines.