lark-cli

1. Overview

• This document describes the official Lark/Feishu CLI tool, commonly referred to as lark-cli, an open-source project maintained by the larksuite team. It is crafted for humans and AI Agents alike, aiming to bridge everyday workflows with automated capabilities across a broad range of business domains.
• At a glance, lark-cli provides control over Messenger, Docs, Base, Sheets, Slides, Calendar, Mail, Tasks, Meetings, and more through a powerful command system that encompasses 200+ commands and 22 AI Agent Skills. This breadth makes it a versatile companion for teams and individual users who rely on Lark/Feishu platforms to get work done.
• The project is released under the MIT license, underscoring its openness and community-friendly nature. The tool is designed to run against Lark/Feishu Open Platform APIs, offering structured and secure interactions that are suitable for both human operators and AI Agents.
• The repository carries recognizable badges that signal essential details: licensing, Go version compatibility, and npm availability. Specifically, the badges indicate the MIT license, Go version compatibility (≥ 1.23), and the NPM package status. These badges are commonly displayed at the top of the project page to convey quick, essential information. For reference, the relevant badges from the input include:
• License badge: MIT
• Go version badge: ≥1.23
• NPM version badge: @larksuite/cli
• A star history visualization is included to reflect the project’s popularity and evolution over time, demonstrating ongoing community engagement and interest.
• The CLI is positioned as user-friendly and agent-friendly. Its architecture emphasizes three layers: Shortcuts, API Commands, and Raw API calls. This design enables users and AI Agents to choose the appropriate level of granularity, from convenient, high-level actions to exhaustive, low-level API interactions.

1. Why lark-cli?

• Agent-Native Design: Out of the box, lark-cli ships with 22 structured AI Agent Skills, enabling agents to operate within Lark with minimal setup. This design reduces friction for AI workflows and accelerates integration with existing AI toolchains.
• Wide Coverage: The tool spans 14 business domains and offers 200+ curated commands, alongside 22 AI Agent Skills. This breadth supports a wide array of daily tasks—from communication and document handling to analytics and project management.
• AI-Friendly & Optimized: Commands are crafted and tested with real Agents in mind. Parameters are concise, defaults are smart, and outputs are structured to maximize the success rate of Agent calls and downstream automation.
• Open Source & Accessible: The MIT license keeps barriers low for adoption, modification, and distribution. A simple npm install gets you up and running quickly.
• Fast Onboarding: A three-minute setup promise—one-click app creation, straightforward interactive login, and the first API call after installation—ensures you move from install to action rapidly.
• Secure & Controllable: Built-in input injection protections, terminal output sanitization, and OS-native keychain credential storage contribute to safer operation in mixed human–machine workflows.
• Three-Layer Architecture: Shortcuts (readable to humans and AI), API Commands (platform-aligned and crawl-ready via OAPI), and Raw API (full coverage). This layered approach lets users pick the right granularity for a given task.
• The combination of these qualities makes lark-cli adaptable to both personal productivity and enterprise-grade automation, while remaining respectful of security and privacy considerations.

1. Core Features and Domain Capabilities

• Calendar (📅): View agendas, create events, invite attendees, check free/busy status, and receive time suggestions. These capabilities enable planning with both humans and AI Agents in real time.
• Messenger (💬): Send and reply to messages, manage group chats, view chat history and threads, search messages, and download media. The experience is designed to support conversational workflows and rapid information retrieval.
• Docs (📄): Create, read, update, and search documents, and handle read/write media and whiteboards. This domain supports content creation and collaborative editing.
• Drive (📁): Upload and download files, search docs and wikis, and manage comments. It provides file-system-like operations within the Lark/Feishu ecosystem.
• Base (📊): Create and manage tables, fields, records, views, dashboards, workflows, forms, and manage roles and permissions. Data aggregation and analytics are supported at scale.
• Sheets (📈): Create, read, write, append, find, and export spreadsheet data, enabling structured data manipulation and analysis.
• Slides (🖼️): Create and manage presentations, read content, and add or remove slides. This domain facilitates presentation workflows and automation.
• Tasks (✅): Create, query, update, and complete tasks; manage task lists, subtasks, comments, and reminders. It is a robust project-task management tool.
• Wiki (📚): Create and manage knowledge spaces, nodes, and documents. This supports knowledge management and organizational memory.
• Contact (👤): Search users by name, email, or phone; retrieve user profiles. Facilitates identity resolution and contact intelligence.
• Mail (📧): Browse, search, read emails, send, reply, forward, manage drafts, and watch for new mail. Email automation is streamlined through the CLI.
• Meetings (🎥): Search meeting records, query minutes and recordings. Access to meeting artifacts supports knowledge capture and review.
• Attendance (🕐): Query personal attendance check-in records, enabling time-tracking insights.
• Approval (✍️): Query approval tasks, approve/reject/transfer tasks, cancel and CC instances. Workflow governance is supported through these controls.
• OKR (🎯): Query and create OKRs; manage objectives and key results, alignments and indicators.
• Project (📋 Project): Meegle — manage work items, schedules, and data via the standalone meegle-cli. This domain is integrated yet distinct and can be extended through a separate installation.

1. Installation & Quick Start

• Requirements
• Node.js with npm or npx
• Go v1.23 or newer
• Python 3 (only required for building from source)
• Quick Start for Humans
• Option 1 — From npm (recommended):
  • Install CLI: npm install -g @larksuite/cli
  • Install CLI SKILL (required): npx skills add larksuite/cli -y -g
• Option 2 — From source:
  • Clone and build: git clone https://github.com/larksuite/cli.git; cd cli; make install
  • Install CLI SKILL (required): npx skills add larksuite/cli -y -g
• Configure & Use
• One-time interactive setup to configure app credentials: lark-cli config init
• Interactive login with recommended scopes: lark-cli auth login --recommend
• Start using capabilities such as calendar +agenda: lark-cli calendar +agenda
• The process is designed to be approachable for both end users and developers who wish to build automation around Lark/Feishu APIs.

1. Quick Start for AI Agents

• The AI Agent path mirrors human onboarding but emphasizes non-human orchestration and browser-assisted steps where required.
• Step 1 — Install
• npm install -g @larksuite/cli
• npx skills add larksuite/cli -y -g
• Step 2 — Configure app credentials
• Run lark-cli config init --new in the background. It prints an authorization URL that can be shared with the user to complete the setup in the browser.
• Step 3 — Login
• Run lark-cli auth login --recommend in the background, then send the authorization URL to the user to complete authentication.
• Step 4 — Verify
• Check status with lark-cli auth status to verify successful login and scope grants.

1. Agent Skills

• The tool ships with a suite of AI Agent Skills and a shared foundation that enables secure, identity-aware interactions:
• lark-shared: Core app config, auth login, identity switching, scope management, security rules (auto-loaded by all other skills).
• lark-calendar: Calendar events, agenda view, free/busy queries, time suggestions.
• lark-im: Messaging—send/reply, group chats, message search, upload/download, and reactions.
• lark-doc: Document creation, reading, updating, and searching (Markdown-based).
• lark-drive: File uploads/downloads with permission and comment management.
• lark-sheets: Spreadsheets creation and manipulation (read, write, append, find, export).
• lark-slides: Presentation handling, content reading, slide addition/removal.
• lark-base: Data structures—tables, fields, records, views, dashboards, analytics.
• lark-task: Task management, subtasks, reminders, and member assignment.
• lark-mail: Email workflows—browse, read, send, reply, forward, drafts, watch for new mail.
• lark-contact: User lookups by name, email, or phone; profiles.
• lark-wiki: Knowledge spaces, nodes, and documents.
• lark-event: Real-time WebSocket subscriptions, regex routing, and agent-friendly formatting.
• lark-vc: Meeting records search, minutes, transcripts, and summaries.
• lark-whiteboard: Whiteboard and chart DSL rendering.
• lark-minutes: Minutes metadata, AI artifacts, summaries, todos, chapters.
• lark-openapi-explorer: Explore APIs from official docs.
• lark-skill-maker: Custom skill creation framework.
• lark-attendance: Personal attendance check-in records.
• lark-approval: Task approvals, rejections, transfers, cancellations, CCs.
• lark-workflow-meeting-summary: Meeting minutes aggregation and structured reports.
• lark-workflow-standup-report: Agenda and todo summaries.
• These skills can be mixed and matched to compose complex automation that spans scheduling, messaging, document handling, and analytics.

1. Authentication

• The CLI supports a range of authentication commands to manage credentials and scopes:
• auth login: OAuth login with interactive domain and scope selection or CLI flags.
• auth logout: Sign out and remove stored credentials.
• auth status: Display current login status and granted scopes.
• auth check: Verify the presence of a specific scope (exit code 0 if OK, 1 if missing).
• auth scopes: List all available scopes for the app.
• auth list: List all authenticated users.
• Example commands:
• Interactive login with domain filtering: lark-cli auth login
• Filter by domain: lark-cli auth login --domain calendar,task
• Auto-approve commonly used scopes: lark-cli auth login --recommend
• Exact scope: lark-cli auth login --scope "calendar:calendar:read"
• Device-code style (agent mode, non-blocking): lark-cli auth login --domain calendar --no-wait
• Resume polling later: lark-cli auth login --device-code
• Identity switching for commands: lark-cli calendar +agenda --as user
• This authentication model ensures users and agents can operate within bounded permissions and supports dynamic switching between identities when needed.

1. Three-Layer Command System

• The CLI exposes three tiers of command granularity to meet different user needs: 1) Shortcuts (Prefix with +): These are human- and AI-friendly, include smart defaults, present table output, and offer dry-run previews. Examples:
  • 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 $'Weekly Report\n# Progress\n- Completed feature X'
  • You can discover all shortcuts by running lark-cli --help. 2) API Commands: Auto-generated from Lark OAPI metadata and curated through quality gates. They map 1:1 to platform endpoints, delivering over 100+ commands like:
  • lark-cli calendar calendars list
  • lark-cli calendar events instanceview --params '{"calendarid":"primary","starttime":"1700000000","endtime":"1700086400"}' 3) Raw API Calls: Direct, low-level access to any Lark Open Platform endpoint, covering thousands of APIs. Examples:
  • lark-cli api GET /open-apis/calendar/v4/calendars
  • lark-cli api POST /open-apis/im/v1/messages --params '{"receiveidtype":"chatid"}' --data '{"receiveid":"ocxxx","msgtype":"text","content":"{\"text\":\"Hello\"}"}'
• This three-layer system gives users precise control when needed while preserving ease of use for routine tasks. It is designed to support both human operators and AI Agents working in concert with Lark/Feishu APIs.

1. Advanced Usage

• Output formats
• The CLI supports multiple output formats to suit different consumption needs:
  • --format json: Full JSON response (default)
  • --format pretty: Human-friendly formatted output
  • --format table: Readable tabular output
  • --format ndjson: Newline-delimited JSON for piping
  • --format csv: Comma-separated values
• Pagination
• When dealing with paginated data, the tool offers:
  • --page-all: Auto-paginate through all pages
  • --page-limit N: Limit to N pages
  • --page-delay MS: Delay between page requests
• Dry Run
• For commands with potential side effects, you can preview with:
  • --dry-run
• Example: lark-cli im +messages-send --chat-id oc_xxx --text "hello" --dry-run
• Schema Introspection
• Inspect API methods, their parameters, requests, responses, and scope requirements:
  • lark-cli schema
  • lark-cli schema calendar.events.instance_view
  • lark-cli schema im.messages.delete
• These capabilities give power users and developers the ability to explore, validate, and orchestrate complex interactions with high confidence and visibility.

1. Security & Risk Warnings (Read Before Use)

• Important notice: This tool can be invoked by AI Agents to automate operations on the Lark/Feishu Open Platform. It carries inherent risks such as model hallucinations, unpredictable execution, and prompt injection. Once authorized, the AI Agent can act under your user identity within the granted scopes, potentially leading to sensitive data leakage or unintended operations.
• Security protections are enabled by design, including default safeguards across multiple layers. However, risks remain, and prudent usage is advised. Do not alter default security settings in a way that weakens protections; relaxing restrictions can substantially amplify risk.
• Recommendation: Use the Lark/Feishu bot integrated with this tool as a private assistant for conversational tasks, rather than exposing it broadly in groups or to multiple users. Thoroughly understand all usage risks and assume responsibility for the outcomes when using automation with Open Platform APIs.
• In short, exercise caution, validate commands and scopes, and consider limiting exposure to trusted accounts and workflows to minimize potential abuse or data exposure.

1. Star History

• The project’s popularity and momentum can be visually tracked over time via a Star History chart. This visualization provides a quick sense of community adoption and ongoing maintenance activity.
• The star history indicator, together with other badges, reflects continuous engagement and contribution from the community, which is a positive signal for developers evaluating the project.

1. Contributing

• Community contributions are welcome and encouraged. If you encounter a bug or have feature ideas, you can engage through:
• Issues: Submit a GitHub issue to report bugs or request features.
• Pull Requests: Propose changes through PRs and collaborate with maintainers.
• For major architectural changes or substantial feature additions, it is recommended to discuss your idea via an Issue first to ensure alignment and avoid duplication of effort.
• Working together with the maintainers helps sustain the project’s quality, security, and usefulness for a broad audience of developers, operators, and AI-driven workflows.

1. License

• The project is released under the MIT License, a permissive open-source license that facilitates reuse and adaptation with minimal restrictions.
• When running, lark-cli calls Lark/Feishu Open Platform APIs. To use these APIs, you must comply with applicable terms and policies:
• Feishu User Terms of Service
• Feishu Privacy Policy
• Feishu Open Platform App Service Provider Security Management Specifications
• Lark User Terms of Service
• Lark Privacy Policy
• The license and terms emphasize user responsibility and the need to respect data privacy and platform guidelines while leveraging automated capabilities.

Appendix: Quick Reference and Practical Scenarios

• Quick install recap
• npm install -g @larksuite/cli
• npx skills add larksuite/cli -y -g
• A compact workflow for a typical user
• Install and configure credentials
• Log in with recommended scopes
• Use calendar +agenda to schedule a meeting and send invites
• Retrieve documents with Docs and attach related media
• Export a summary to a Sheets or a Wiki page for team visibility
• Common command patterns
• Shortcuts: lark-cli calendar +agenda
• API Commands: lark-cli calendar events list
• Raw API: lark-cli api GET /open-apis/calendar/v4/calendars
• Platform awareness
• The CLI is designed to respect platform terms and privacy policies, and users should be mindful of data sensitivity when using AI agents to perform operations on live data.

Images included from the Input

• License badge
• Go version badge
• NPM version badge
• Star History

Notes on usage and tone

• The description above preserves the original content’s intent while reorganizing it into a multi-section narrative with numbered headings and bullet points. It emphasizes practical usage, architectural design, security considerations, and avenues for contribution.
• Where helpful, concrete command examples and step-by-step workflows are included to guide both human users and AI Agents through typical tasks, from installation to advanced API exploration.
• While the original input contains numerous technical specifics, this description focuses on delivering a coherent, readable guide that highlights capabilities, usage patterns, and safety considerations without resorting to tabular formatting.