Lark Cli

Lark CLI

This skill uses the lark CLI to operate Feishu/Lark products (IM, Drive, Docs, Sheets, Mail, Calendar, Wiki, Bitable, Tasks, and more), with the shortest-path examples and reference links.

What this repo provides

• lark CLI: a single binary to access Feishu/Lark products (IM, Drive, Docs, Sheets, Mail, Calendar, Wiki, Bitable, Tasks).
• Two output modes: human tables by default, JSON with --json for automation.
• SDK-first implementation via the official oapi-sdk-go.

Quickstart (minimal)

1) Install the CLI (see references/INSTALL.md). 2) Authenticate:

• Tenant token (app-only, bot/app identity): lark auth tenant
• User token (user-scoped, on behalf of a user): lark auth user login

See references/AUTH.md for details and scopes. 3) Run a command:

lark whoami
lark chats list --limit 10
lark users search "Ada" --json

Core concepts (tl;dr)

• Feishu = Lark (global brand). Same API surface, different API endpoints.
• Most commands follow: lark <product> <action> [args] [flags].
• Required IDs are positional args (no required --id flags).
• Many commands accept a Lark/Feishu web URL in place of IDs.
• --json prints machine-readable output to stdout; logs/errors go to stderr.

See references/CONCEPTS.md for a longer primer.

When to use tenant vs user tokens

• Tenant token: app-level operations as your bot/app identity.
• User token: user-scoped operations on behalf of a specific user.

If a command fails with scope errors, check references/TROUBLESHOOTING.md.

Token Type Usage

Use --token-type to force the access token type:

• --token-type auto: default, auto-select based on command needs.
• --token-type tenant: force tenant token.
• --token-type user: force user token.

Examples:

lark whoami --token-type tenant
lark drive list --token-type user

Agent-friendly workflow

• Prefer --json and parse in tools/scripts.
• Use --limit / --pages for pagination-heavy commands.
• Reuse --account or LARK_ACCOUNT for multi-user scenarios.

User-facing output style (important)

When you execute lark commands on the user's behalf:

• Do not dump raw CLI commands or verbose terminal output to the user by default.
• Summarize results in human-readable language (what changed / what was found / next action).
• Only include the exact command/output when the user explicitly asks, or when it's needed for debugging/repro.
• Prefer short lists and direct links (Docx/Sheet URLs) over IDs/tokens.

Common recipes

See references/RECIPES.md for common tasks (send message, search users, read docs, etc.).

Deep references

• Install: references/INSTALL.md
• Auth & scopes: references/AUTH.md
• Concepts & IDs: references/CONCEPTS.md
• Recipes: references/RECIPES.md
• Troubleshooting: references/TROUBLESHOOTING.md
• Completion: references/COMPLETION.md
• Docs: references/DOCS.md
• Sheets: references/SHEETS.md
• Bitable bases: references/BASES.md
• Drive: references/DRIVE.md
• Minutes: references/MINUTES.md
• Calendars: references/CALENDARS.md
• Meetings: references/MEETINGS.md
• Chats: references/CHATS.md
• Messages: references/MESSAGES.md
• Contacts: references/CONTACTS.md
• Mail: references/MAIL.md
• Tasklists: references/TASKLISTS.md
• Tasks: references/TASKS.md
• Users: references/USERS.md
• Config: references/CONFIG.md
• Whoami: references/WHOAMI.md
• Wiki: references/WIKI.md

Auth & Tokens

Token types

• Tenant token: app-only access using your bot/app identity (admin/app-level APIs).
• User token: user-scoped access on behalf of a specific user (Drive search, Mail send, user mailbox, etc.).

Store app credentials

lark auth login --app-id <APP_ID> --app-secret <APP_SECRET>

Optionally store the app secret in the OS keychain:

lark auth login --app-id <APP_ID> --app-secret <APP_SECRET> --store-secret-in-keyring

Get tokens

Tenant token:

lark auth tenant

User token:

lark auth user login

Multiple accounts

Use --account or LARK_ACCOUNT to select a user account.

Scope errors

If a command fails with missing permissions, check:

• Whether it requires a user token.
• Whether the account granted required scopes.

See references/TROUBLESHOOTING.md for quick fixes.

Bitable Bases (Base) Workflows

Bitable is Lark/Feishu's database product. Most commands require a base app token.

List bases (apps)

lark bases list --limit 10

List tables in a base

lark bases table list --app-token <APP_TOKEN>

Create a table

lark bases table create "Leads" --app-token <APP_TOKEN>

Create a field

lark bases field create <TABLE_ID> --app-token <APP_TOKEN> \
  --name "Owner" --type user

Create a record

lark bases record create <TABLE_ID> --app-token <APP_TOKEN> \
  --field Name=Acme --field Score:=42

Search records

lark bases record search <TABLE_ID> --app-token <APP_TOKEN> --json

Calendars Workflows

Calendars contain events. Times are RFC3339 (UTC or with timezone offset).

List events

lark calendars list --limit 10 --start 2026-02-01T00:00:00Z --end 2026-02-08T00:00:00Z

Search events by keyword

lark calendars search "standup" --limit 10 --start 2026-02-01T00:00:00Z --end 2026-02-08T00:00:00Z

Get event details

lark calendars get <EVENT_ID>

Chats Workflows

Chats are conversations the bot can access.

List chats

lark chats list --limit 10

Create a chat

lark chats create --name "Project Alpha" --user-id <OPEN_ID>

Get chat details

lark chats get <CHAT_ID>

Update chat name

lark chats update <CHAT_ID> --name "New Name"

Read or update announcements

lark chats announcement get <CHAT_ID>
lark chats announcement update <CHAT_ID> --revision 12 --request '{"requestType":"InsertBlocksRequestType"}'

Completion Workflows

Generate shell completion scripts.

Bash

lark completion bash

Zsh

lark completion zsh

Fish

lark completion fish

PowerShell

lark completion powershell

Concepts & IDs (Primer)

This primer is for agents new to Feishu/Lark.

Feishu vs Lark

• Feishu is the China brand.
• Lark is the global brand.
• API surface and identifiers are the same; UI labels may differ.
• API endpoints differ by brand/region; use --platform feishu|lark to select.

Product map (common)

• IM: chats, messages
• Drive: files, permissions
• Docs/Sheets: docx, sheets
• Mail: mailboxes, messages
• Calendar: calendars, events
• Wiki: spaces, nodes
• Bitable: bases, tables, records
• Tasks: tasklists, tasks

IDs and tokens

• Most commands take IDs as positional args.
• Many commands accept Lark/Feishu web URLs and extract IDs automatically.

Examples:

lark docs info <doc-id>
lark docs info https://.../docx/<doc-token>
lark drive info <file-token>

Output modes

• Default: human-readable tables/text.
• --json: machine-readable output to stdout; logs/errors to stderr.

Pagination

• Use --limit for list size.
• Use --pages for page count when available.

Config Workflows

Config controls defaults like platform, mailbox, and app credentials.

Show config

lark config info

Set platform or base URL

lark config set --platform feishu
lark config set --base-url https://open.larksuite.com

Set default mailbox ID

lark config set --default-mailbox-id <MAILBOX_ID>

Set default token type

lark config set --default-token-type user

Set app credentials

lark config set --app-id <APP_ID>
lark config set --app-secret <APP_SECRET>

Unset values

lark config unset --base-url true
lark config unset --default-mailbox-id true
lark config unset --default-token-type true
lark config unset --default-user-account true
lark config unset --user-tokens true

List supported keys

lark config list-keys

Contacts Workflows

Contacts expose the organization directory. The current CLI exposes contact user info.

Get contact user info

lark contacts user info --user-id <USER_ID>

If you need a user ID, use search first:

lark users search "Ada" --json

Docs (Docx) Workflows

Docs in this CLI refer to Docx documents. Most commands accept a Docx token or a Docx URL.

Read doc content

Markdown (default):

lark docs get <DOCX_TOKEN> --format md

Plain text:

lark docs get <DOCX_TOKEN> --format txt

Blocks (structured JSON/table):

lark docs get <DOCX_TOKEN> --format blocks --json

Download Markdown then overwrite

Download to a file:

lark docs get <DOCX_TOKEN> --format md > doc.md

Edit doc.md, then overwrite the Docx content:

lark docs overwrite <DOCX_TOKEN> --content-file doc.md

Convert Markdown/HTML to blocks

lark docs convert --content-type markdown --content "# Title"

Overwrite with HTML

lark docs overwrite <DOCX_TOKEN> --content-type html --content-file page.html

Drive Workflows

Drive is the file storage layer for Docs, Sheets, Slides, Minutes, and uploaded files.

List files in a folder

lark drive list --folder-id <FOLDER_TOKEN> --limit 20

Search files by keyword

lark drive search "Q1" --limit 10 --json

If you hit permission errors, re-run with a user token:

lark auth user login

Inspect a file

lark drive info <FILE_TOKEN>

Get share URLs

lark drive urls <FILE_TOKEN>

Download a file

lark drive download <FILE_TOKEN> --out ./file.bin

Upload a file

lark drive upload ./report.pdf --folder-token <FOLDER_TOKEN>

Manage permissions

lark drive permissions add <FILE_TOKEN> openid <OPEN_ID> --type docx --perm view --member-kind user
lark drive permissions list <FILE_TOKEN> --type docx
lark drive permissions update <FILE_TOKEN> openid <OPEN_ID> --type docx --perm edit
lark drive permissions delete <FILE_TOKEN> openid <OPEN_ID> --type docx

Install (Detailed)

This file is intentionally separate from SKILLS.md so one-time setup does not clutter the agent quickstart.

Homebrew (macOS)

brew tap rintays/tap
brew install rintays/tap/lark

Build from source

git clone https://github.com/rintays/lark-cli.git
cd lark
go install ./cmd/lark
lark --help

Local binary:

go build -o lark ./cmd/lark
./lark --help

GitHub Releases

Download the archive for your OS from the releases page, extract it, and move lark into your PATH.

macOS/Linux example:

curl -L https://github.com/rintays/lark-cli/releases/latest/download/lark_<VERSION>_darwin_arm64.tar.gz -o lark.tar.gz
tar -xzf lark.tar.gz
chmod +x lark
sudo mv lark /usr/local/bin/lark

Windows (PowerShell) example:

Invoke-WebRequest -Uri https://github.com/rintays/lark-cli/releases/latest/download/lark_<VERSION>_windows_amd64.zip -OutFile lark.zip
Expand-Archive lark.zip -DestinationPath .
Move-Item .\lark.exe $env:USERPROFILE\bin\lark.exe

Verify

lark --help
lark auth --help

Mail Workflows

Mail APIs are user-scoped. You must use a user token.

Login (user token)

lark auth user login

List folders

lark mail folders

List inbox messages

lark mail list --folder-id INBOX --limit 10

Get message metadata

lark mail info <MESSAGE_ID>

Get full message content

lark mail get <MESSAGE_ID>

Send email (text)

lark mail send --to user@example.com --subject "Hello" --text "Hi"

Send email (raw EML)

lark mail send --raw-file message.eml

Meetings Workflows

Meetings are scheduled video meetings.

List meetings (defaults to last 6 months)

lark meetings list --limit 10

Get meeting details

lark meetings info <MEETING_ID>

Create a meeting (basic)

lark meetings create --topic "Weekly" --end-time 2026-02-03T01:30:00Z

Update a meeting reservation

lark meetings update <RESERVE_ID> --topic "Weekly Sync"

Delete a meeting reservation

lark meetings delete <RESERVE_ID>

Messages Workflows

Messages are chat messages sent to chats or users.

Send a message

lark messages send <RECEIVE_ID> --receive-id-type chat_id --text "hello"

List messages in a chat

lark messages list <CHAT_ID> --limit 10

Search messages by keyword

lark messages search "incident" --limit 10

Reply to a message

lark messages reply <MESSAGE_ID> --text "got it"

Add a reaction

lark messages reactions add <MESSAGE_ID> thumbs_up

Pin or unpin a message

lark messages pin <MESSAGE_ID>
lark messages unpin <MESSAGE_ID>

Minutes Workflows

Minutes are meeting recordings/transcripts stored in Drive.

List minutes

lark minutes list --limit 20

Filter by folder or title

lark minutes list --folder-id <FOLDER_TOKEN> --query "Weekly" --limit 10

Get minutes details

lark minutes info <MINUTE_TOKEN>

Update sharing permissions

lark minutes update <MINUTE_TOKEN> --link-share tenant_readable --external-access=false

Delete minutes

lark minutes delete <MINUTE_TOKEN>

Recipes (Common Agent Tasks)

These examples are safe starting points. Prefer --json for automation.

Who am I?

lark whoami

List chats

lark chats list --limit 10

Send a message

lark messages send <CHAT_ID> --text "hello"

Search users

lark users search "Ada" --json

Read a doc

lark docs get <DOCX_TOKEN> --format md

Search Drive

lark drive search "Q1" --limit 10 --json

Mail: list inbox

lark mail list --limit 10

Sheets Workflows

Sheets commands accept a spreadsheet token or a spreadsheet URL.

Read

lark sheets read <SHEET_TOKEN> "Sheet1!A1:C10"

Use a sheet ID plus a simple range:

lark sheets read <SHEET_TOKEN> A1:C10 --sheet-id <SHEET_ID>

Update a range

Inline JSON values:

lark sheets update <SHEET_TOKEN> "Sheet1!A1:B2" \
  --values '[["Name","Score"],["Ada",42]]'

Values from file (JSON/CSV/TSV):

lark sheets update <SHEET_TOKEN> "Sheet1!A1:B2" --values-file values.json

Append rows

lark sheets append <SHEET_TOKEN> "Sheet1!A1" --values '[["New","Row"]]'

Clear

lark sheets clear <SHEET_TOKEN> "Sheet1!A1:C10"

Tasklists Workflows

Tasklists group related tasks.

Create a task list

lark tasklists create --name "Backlog"

Get task list details

lark tasklists info <TASKLIST_GUID>

Update a task list

lark tasklists update <TASKLIST_GUID> --name "Team Backlog"

Delete a task list

lark tasklists delete <TASKLIST_GUID>

Tasks Workflows

Tasks are personal or shared work items.

List my tasks

lark tasks list --limit 10

Create a task

lark tasks create --summary "Write report" --due 2026-02-05T12:00:00Z

Update a task

lark tasks update <TASK_GUID> --summary "Write report v2"

Complete a task

lark tasks update <TASK_GUID> --completed-at 2026-02-03T12:00:00Z

Troubleshooting

Permission / scope errors

Symptoms:

• 401/403 errors
• error text mentioning missing scopes or permissions

Fix:

• Use a user token for user-scoped APIs: lark auth user login
• Re-login and grant missing scopes
• Verify the account: lark auth status --json

Command expects positional IDs

Many commands require IDs as positional args (not --id). Example:

lark docs info <DOC_ID>

Not sure which token to use

• Tenant token: app/admin operations
• User token: Drive search, Mail send, user mailboxes, etc.

If unsure, try user token first for user data.

JSON parsing errors

• Ensure you pass --json.
• Logs/errors go to stderr; parse stdout only.

Users Workflows

Users are people in your tenant directory. Search requires a user token.

Search users

lark users search "Ada" --limit 10

Search by email:

lark users search --email "ada@example.com" --limit 10

Get contact user info

lark users info --user-id <USER_ID>

Whoami

Show tenant or user information, depending on the token type resolved.

lark whoami

Use --token-type tenant or --token-type user if you need to force a token type.

Wiki Workflows

Wiki organizes content into spaces and nodes. Many commands accept either tenant or user tokens, but space creation is user-token only.

List spaces

lark wiki space list --limit 10

Create a space (user token required)

lark wiki space create "Team KB" --space-type team --visibility private

List nodes in a space

lark wiki node list --space-id <SPACE_ID> --limit 50

Render a node tree

lark wiki node tree --space-id <SPACE_ID> --depth 3

Create a node (link a Doc/Sheet/etc.)

lark wiki node create docx <DOCX_TOKEN> --space-id <SPACE_ID> --title "Design"

Move a node

lark wiki node move <NODE_TOKEN> --space-id <SPACE_ID> --target-parent-node-token <PARENT_NODE_TOKEN>

Update node title

lark wiki node update-title <NODE_TOKEN> "New Title" --space-id <SPACE_ID>

Note on permissions

If a node points to a Drive object (doc/sheet/file), use lark drive permissions to manage collaborators for the underlying obj_token.