How lark‑cli’s 200+ Commands and 19 Agent Skills Enable AI Agents to Automate Feishu

Why lark-cli?

lark-cli is the first Feishu/Lark command‑line tool explicitly designed for AI Agent scenarios. All commands have been validated by agents; the official README lists over 200 curated commands that are parameter‑friendly, have robust error handling, and produce structured output.

19 built‑in Agent Skills (e.g., lark-calendar for scheduling, lark-im for messaging, lark-mail for email) let agents perform common tasks without writing prompts.

MIT‑licensed and open‑source; the repository can be cloned directly from GitHub.

Feature Overview

lark-cli covers 11 core Feishu business domains, each exposing specific capabilities:

Calendar : view, create, invite, check availability, get time suggestions.

Instant Messaging : send/reply messages, manage groups, search, download media.

Cloud Docs : create, read, update, search, edit boards.

Cloud Space : upload/download files, search knowledge, manage comments.

Multidimensional Tables : create/manage tables, fields, records, views, aggregate data.

Spreadsheets : create/read/write/append/find/export rows.

Tasks : create/query/update/complete tasks, manage subtasks and reminders.

Knowledge Base : manage spaces, nodes, documents.

Address Book : search users by name/email/phone, fetch user info.

Email : browse, search, read, send, reply, forward, listen for new mail.

Video Meetings : search meeting records, retrieve minutes and recordings.

Each domain is accessible via concise Shortcut commands such as +agenda, +messages-send, +chat-create, etc.

Installation & Quick Start

Human‑User Installation (npm)

# Install the CLI via npm
npm install -g @larksuite/cli

# Install required Skills (mandatory)
npx skills add larksuite/cli -y -g

Source Build

git clone https://github.com/larksuite/cli.git
cd cli
make install
# Install Skills as above
npx skills add larksuite/cli -y -g

AI Agent Installation Flow

Agents run a configuration command that prints an authorization URL; the user completes the OAuth flow in a browser while the agent never sees appId or appSecret. lark-cli config init --new Login for agents returns a URL immediately with --no-wait, allowing non‑blocking authentication.

lark-cli auth login --recommend

Agent Skills Deep Dive

lark-shared (Base Layer)

App Configuration : read and manage Feishu app credentials.

Authentication : handle OAuth flows.

Identity Switching : Bot vs User dual identities.

Permission Management : check and prompt for missing scopes.

Security Rules : confirm intent before write operations.

lark-im (Instant Messaging)

Message : single‑message ID format om_xxx.

Chat : group or P2P ID format oc_xxx.

Thread : reply‑thread handling.

Reaction : emoji replies.

Key Shortcut examples: +chat-create – create a group chat as bot. +messages-send – send a message. +messages-reply – reply with thread support. +messages-search – cross‑chat message search.

If a bot’s sender name cannot be resolved, use --as user to switch to user identity.

lark-calendar (Smart Scheduling)

The skill follows an “assistant, not replacement” philosophy. Workflow examples:

User provides a specific time → check busy status → prompt on conflict.

User provides a time range → generate multiple suggestions → execute after user picks.

User provides no time → infer a reasonable slot and propose options.

Smart defaults include automatic participant selection (default to the user), auto‑generated titles, and duration inference based on meeting type (e.g., “review” → 60 minutes).

lark-skill-maker (Custom Skill Extension)

When built‑in Skills are insufficient, developers can create custom Skills using the lark-skill-maker template. Design rules:

Description drives trigger : must contain functional keywords and a “when user needs …” clause.

Permission declaration : explicitly list required scopes.

Security confirmation : ask for user intent before write actions.

Design Principles Summary

Agent‑Native : built for agents from day one.

Assistive Decision‑Making : provide suggestions, let users decide.

Progressive Memory : capture user preferences through dialogue.

Security First : multiple safeguards; credentials never pass through agents.

Authentication System Deep Dive

lark-cli implements a dual Bot vs User identity model.

Acquisition : Bot – automatic with appId + appSecret; User – interactive lark-cli auth login.

Scope : Bot – app‑level, only bot resources; User – user‑level, requires backend scopes + user OAuth.

Visibility : Bot cannot access user calendars, cloud space, email; User can access personal resources.

Authorization : Bot – backend scope configuration only; User – backend scopes + user consent.

OAuth Login Options

# Interactive login (TUI)
lark-cli auth login

# Domain‑filtered login
lark-cli auth login --domain calendar,task

# Recommended auto‑approved scopes
lark-cli auth login --recommend

# Precise scope selection
lark-cli auth login --scope "calendar:calendar:readonly"

# Agent mode (non‑blocking)
lark-cli auth login --domain calendar --no-wait

The --recommend flag supplies a curated set of scopes to reduce manual selection.

Permission Management

When a scope is missing, Bot identity returns a console_url for the user to enable the scope in the developer console. Bot actions are prohibited from invoking auth login to avoid credential leakage.

For User identity, scopes accumulate across multiple logins (incremental authorization).

Three‑Layer Command Architecture

Shortcuts

Prefixed with +, these are human‑friendly one‑liner commands that embed smart defaults, structured output, and optional --dry-run preview.

# View today’s agenda
lark-cli calendar +agenda

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

# Create a document
lark-cli docs +create --title "Weekly Report" --markdown "# Progress
- Completed feature X"

API Commands

Generated from Feishu OAPI metadata, these commands expose the full parameter set of the underlying API while still benefiting from validation and formatting.

# List calendars
lark-cli calendar calendars list

# View a calendar event instance
lark-cli calendar events instance_view --params '{"calendar_id":"primary","start_time":"1700000000","end_time":"1700086400"}'

Raw API Calls

Directly invoke any Feishu endpoint (2500+), useful for unwrapped or experimental APIs.

# GET request example
lark-cli api GET /open-apis/calendar/v4/calendars

# POST request example
lark-cli api POST /open-apis/im/v1/messages \
  --params '{"receive_id_type":"chat_id"}' \
  --body '{"receive_id":"oc_xxx","msg_type":"text","content":"{\"text\":\"Hello\"}"}'

Design Rationale

Shortcuts : cover ~80 % of common scenarios, prioritize simplicity.

API Commands : address ~19 % of complex cases, balance flexibility and usability.

Raw API : handle the remaining ~1 % of edge cases requiring full control.

Security and Best Practices

Input injection protection.

Terminal output sanitization to avoid leaking secrets.

OS‑native keychain storage for credentials.

Dry‑run preview for dangerous operations.

The tool can be invoked by AI agents to automate Feishu operations, but inherent risks such as model hallucination, uncontrolled execution, and prompt injection exist. Granting permissions allows agents to act within the authorized scope, potentially exposing sensitive data or performing over‑privileged actions.

Do not modify default security settings.

Use the bot as a private personal assistant, not in group chats.

Avoid adding the bot to shared conversations.