Feishu

Feishu/Lark Agent Skill

You have access to feishu-cli, a CLI that wraps 1300+ Feishu/Lark Open Platform APIs. Use it to execute any Feishu API call directly from the terminal.

Quick Reference

# Discovery
feishu-cli api list                       # List all API namespaces
feishu-cli api list im                    # List APIs in a namespace
feishu-cli api search <keyword>           # Search APIs by keyword
feishu-cli api info <tool-name>           # Full metadata + parameter schema

# Execution (structured JSON I/O, never throws)
feishu-cli exec <tool-name> --params '<json>' --output json
feishu-cli exec <tool-name> --dry-run --params '<json>'   # Validate only
echo '<json>' | feishu-cli exec --stdin --output json      # Pipe input
feishu-cli exec --batch --params '[...]' --output json     # Batch execute

# High-level commands
feishu-cli msg send --to <email> --text "Hello"
feishu-cli doc import <file> --title "Title"
feishu-cli doc export <document-id> -o output.md
feishu-cli auth status                    # Check token validity

Workflow: Discover → Validate → Execute

Always follow this pattern. Do NOT guess tool names or parameter shapes.

Step 1: Discover the Right Tool

# Start with keyword search
feishu-cli api search "chat list"

# Browse a namespace
feishu-cli api list im

# Inspect parameters before calling
feishu-cli api info im.v1.chat.list

Tool names follow the pattern: <project>.<version>.<resource>.<action>

• im.v1.chat.list — List chats
• im.v1.message.create — Send a message
• docx.v1.document.rawContent — Get document content
• drive.v1.file.list — List Drive files

Step 2: Validate (Optional but Recommended)

feishu-cli exec im.v1.chat.list --dry-run --params '{"params":{"page_size":5}}' --output json

Dry-run checks tool existence, parameter validity, and token compatibility without making an API call.

Step 3: Execute

feishu-cli exec im.v1.chat.list --params '{"params":{"page_size":20}}' --output json

Output is always structured JSON:

{"ok": true, "data": {"items": [...], "has_more": false}}
{"ok": false, "error": {"code": "AUTH_REQUIRED", "message": "..."}}

Pagination

For paginated APIs, add --all to automatically fetch every page:

feishu-cli exec im.v1.chat.list --params '{"params":{"page_size":100}}' --all --output json

Parameter Structure

API parameters are organized into three layers. Use feishu-cli api info <tool> to see which layers a tool accepts.

{
  "path": {},
  "params": {},
  "data": {}
}

Token Routing

feishu-cli supports two token types:

• If a tool only supports user tokens, feishu-cli auto-switches. No action needed.
• If you get AUTH_REQUIRED, run feishu-cli auth status to check, then feishu-cli auth login if needed.
• For user-scoped operations (search, personal docs), explicitly add --token-mode user.

Error Handling

All errors are structured. Check error.code to decide recovery:

Common Recipes

Get Current User

When you need to know who is logged in (e.g. to send them a message), use authen.v1.userInfo.get:

feishu-cli exec authen.v1.userInfo.get --token-mode user --output json

Returns open_id, user_id, name, union_id, etc. Use the open_id as the recipient for messaging APIs.

Send a Message

# Via high-level command — by email
feishu-cli msg send --to user@example.com --text "Hello from CLI"

# Via high-level command — by open_id
feishu-cli msg send --to ou_xxx --receive-id-type open_id --text "Hello"

# Via exec (more control)
feishu-cli exec im.v1.message.create --params '{
  "params": {"receive_id_type": "open_id"},
  "data": {
    "receive_id": "ou_xxx",
    "msg_type": "text",
    "content": "{\"text\": \"Hello from CLI\"}"
  }
}' --output json

Note: content is a JSON-encoded string inside the data object.

To message the current user: first call authen.v1.userInfo.get to get their open_id, then use it as the recipient.

List Chats

feishu-cli exec im.v1.chat.list --params '{"params":{"page_size":20}}' --all --output json

Search Messages

feishu-cli exec search.v2.message.create --params '{
  "data": {"query": "keyword"}
}' --token-mode user --output json

Create a Document

# Import a local file
feishu-cli doc import README.md --title "My Document"

# Create empty doc via API
feishu-cli exec docx.v1.document.create --params '{
  "data": {"title": "New Document", "folder_token": "fldcnXXX"}
}' --output json

Read Document Content

# Export to markdown
feishu-cli doc export <document_id> -o output.md

# Raw content via API
feishu-cli exec docx.v1.document.rawContent --params '{
  "path": {"document_id": "Rnxxxxxxxxx"}
}' --output json

List Drive Files

feishu-cli exec drive.v1.file.list --params '{
  "params": {"folder_token": "fldcnXXX", "page_size": 50}
}' --output json

Get User Info

# Current logged-in user (requires user token)
feishu-cli exec authen.v1.userInfo.get --token-mode user --output json

# Look up another user by open_id
feishu-cli exec contact.v3.user.get --params '{
  "path": {"user_id": "ou_xxx"},
  "params": {"user_id_type": "open_id"}
}' --output json

Batch Operations

feishu-cli exec --batch --params '[
  {"tool": "im.v1.chat.list", "params": {"params": {"page_size": 5}}},
  {"tool": "contact.v3.user.get", "params": {"path": {"user_id": "ou_xxx"}, "params": {"user_id_type": "open_id"}}}
]' --output json

Prerequisites

Before first use, ensure credentials are configured:

# Check current auth state
feishu-cli auth status

# If not configured, set app credentials
feishu-cli config init              # Interactive setup
# Or set environment variables:
# FEISHU_APP_ID, FEISHU_APP_SECRET

# For user-scoped APIs, authenticate via OAuth
feishu-cli auth login

Tips for Agents

1. Always use --output json for machine-readable output.
2. Prefer exec over generated subcommands — it has structured I/O and never throws.
3. Use --dry-run first when unsure about parameters.
4. Use --all for list APIs to avoid manual pagination.
5. Check feishu-cli api info before constructing params — don't guess schemas.
6. Use --compact to reduce output size when processing large results.
7. Content fields are double-encoded — message content is a JSON string inside JSON.
8. Batch when possible — --batch reduces round-trips for independent operations.