Lark/Feishu CLI Tool

## Tech Stack

- **Primary Language**: Go (v1.23+)
- **Secondary Languages**: JavaScript, Python, Shell
- **License**: MIT
- **Package**: @larksuite/cli (npm)
- **Stars**: 12,600+ on GitHub

## Key Features

- 18 business domains covered
- 200+ curated commands
- 26 AI Agent skills (lark-calendar, lark-im, lark-doc, etc.)
- Three-layer command system (shortcuts, API commands, raw API)
- Built-in OAuth authentication
- Multiple output formats (JSON, table, CSV, etc.)
- Pagination and dry-run support

# Required for all installations:
# - Node.js with npm/npx

# Only required if building from source:
# - Go v1.23 or later
# - Python 3

# Install lark-cli globally
npx @larksuite/cli@latest install

# Verify installation
lark-cli --version

# Clone the repository
git clone https://github.com/larksuite/cli.git
cd cli

# Build and install
make install

# Install CLI SKILL (required for AI Agent integration)
npx skills add larksuite/cli -y -g

# Verify installation
lark-cli --version

# Run the interactive configuration wizard
lark-cli config init

# The wizard will:
# 1. Guide you to create a new Lark/Feishu app
# 2. Output an authorization URL to complete setup in browser
# 3. Store app credentials (app_id, app_secret) in your OS keychain

# Interactive login (recommended for first-time setup)
lark-cli auth login

# Auto-select commonly used scopes
lark-cli auth login --recommend

# Login with specific domains (e.g., calendar and tasks)
lark-cli auth login --domain calendar,im,docs

# Login with exact scope
lark-cli auth login --scope "calendar:calendar:read calendar:calendar:write"

# Check authentication status
lark-cli auth status

# List all available scopes for your app
lark-cli auth scopes

# List authenticated users/identities
lark-cli auth list

# Check auth status
lark-cli auth status

# Run a simple command - view calendar agenda
lark-cli calendar +agenda

# Check available commands
lark-cli --help
lark-cli calendar --help

# 1. SHORTCUTS - Human/AI-friendly, smart defaults (prefixed with +)
lark-cli calendar +agenda
lark-cli im +messages-send --chat-id "oc_xxx" --text "Hello"
lark-cli docs +create --api-version v2 --doc-format markdown --content "# My Doc"

# 2. API COMMANDS - Mapped 1:1 to platform endpoints (100+ commands)
lark-cli calendar calendars list
lark-cli calendar events instance_view --params '{"calendar_id":"primary","start_time":"1700000000","end_time":"1700086400"}'

# 3. RAW API CALLS - Full access to 2500+ Lark Open Platform APIs
lark-cli api GET /open-apis/calendar/v4/calendars
lark-cli api POST /open-apis/im/v1/messages --params '{"receive_id_type":"chat_id"}' --data '{"receive_id":"oc_xxx","msg_type":"text","content":"{\"text\":\"Hello\"}"}'

## Available AI Agent Skills

| Skill | Description |
|-------|-------------|
| lark-shared | App config, auth login, scope management (auto-loaded) |
| lark-calendar | Calendar events, agenda view, free/busy queries |
| lark-im | Send/reply messages, group chat management |
| lark-doc | Create, read, update, search documents |
| lark-drive | Upload, download files, manage permissions |
| lark-markdown | Drive-native Markdown files |
| lark-sheets | Spreadsheet operations |
| lark-slides | Presentation management |
| lark-base | Tables, records, views, dashboards, analytics |
| lark-task | Tasks, task lists, subtasks |
| lark-mail | Email browse, send, reply, draft management |
| lark-contact | Search users by name/email/phone |
| lark-wiki | Knowledge spaces and documents |
| lark-event | Real-time event subscriptions (WebSocket) |
| lark-vc | Meeting records and minutes |
| lark-whiteboard | Whiteboard/chart DSL rendering |
| lark-minutes | Minutes metadata and AI artifacts |
| lark-openapi-explorer | Explore underlying APIs |
| lark-skill-maker | Custom skill creation framework |
| lark-attendance | Query attendance check-in records |
| lark-approval | Approval workflow management |
| lark-workflow-meeting-summary | Meeting minutes aggregation |
| lark-workflow-standup-report | Agenda and todo summary |
| lark-okr | OKR query, create, update

# Output Formats
lark-cli calendar +agenda --format json      # JSON (default)
lark-cli calendar +agenda --format pretty    # Human-friendly formatted
lark-cli calendar +agenda --format table     # Readable table
lark-cli calendar +agenda --format ndjson    # Newline-delimited JSON
lark-cli calendar +agenda --format csv       # Comma-separated values

# Pagination (for commands with multiple pages)
lark-cli calendar events list --page-all              # Auto-paginate all pages
lark-cli calendar events list --page-limit 5          # Max 5 pages
lark-cli calendar events list --page-delay 500        # 500ms between requests

# Dry Run (preview requests before executing)
lark-cli im +messages-send --chat-id oc_xxx --text "hello" --dry-run

# Schema Introspection (inspect API parameters and structure)
lark-cli schema
lark-cli schema calendar.events.instance_view
lark-cli schema im.messages.delete

# Identity Switching (execute as user or bot)
lark-cli calendar +agenda --as user
lark-cli im +messages-send --as bot --chat-id "oc_xxx" --text "Hello"

## Security & Risk Warnings

### Built-in Protections

- Input injection protection
- Terminal output sanitization
- OS-native keychain credential storage

### Use with Caution

This tool can be invoked by AI Agents to operate on Lark/Feishu. Risks include:

- Model hallucinations leading to unintended operations
- Prompt injection vulnerabilities
- Data leakage through unauthorized access
- Accidental data modification or deletion

### Recommendations

1. Do NOT modify default security settings
2. Use Lark/Feishu bot as a private conversational assistant
3. Do NOT add the bot to group chats
4. Avoid allowing other users to interact with the bot
5. Fully understand all usage risks before deployment

By using this tool, you voluntarily assume all related responsibilities.

## Common Issues

### Auth fails after config init

**Solution**: Make sure you completed the browser-based app creation flow. The config init command waits for you to finish setting up the app in your browser.

### Missing scopes error

**Solution**: Re-login with the required scopes:
```bash
lark-cli auth login --domain calendar,im,docs
```

### Command not found

**Solution**: Check available commands:
```bash
lark-cli --help
lark-cli <service> --help
```

### Need to switch between multiple accounts

**Solution**: Use auth list to see authenticated identities and specify --as user or --as bot in commands:
```bash
lark-cli auth list
lark-cli calendar +agenda --as user
```

### Build from source fails

**Solution**: Ensure you have Go v1.23+ and Python 3 installed:
```bash
go version
python3 --version
```

## Links

- **GitHub Repository**: https://github.com/larksuite/cli
- **npm Package**: https://www.npmjs.com/package/@larksuite/cli
- **License**: MIT
- **Lark/Feishu Open Platform**: https://www.larksuite.com/open-plateform
- **Issue Tracker**: https://github.com/larksuite/cli/issues

## Community

- Submit bugs and feature requests via Issues
- Discuss major changes via Issues before creating PRs
- Join the community for support and updates