Feishu CLI Document Operations

Create, read, update, and search cloud documents with Lark-flavored Markdown. Insert media, manage whiteboards, and download resources — all from the command line or through AI Agent automation.

Overview

Cloud Document Management from the Terminal

The Feishu CLI document module provides 6 shortcut commands for comprehensive cloud document control. Every shortcut maps directly to the Lark Open Platform Docs API via MCP tool calls, giving you full programmatic access to Feishu/Lark documents.

Key capabilities include:

Full Markdown-based creation — create rich documents using Lark-flavored Markdown with callouts, grids, tables, images, and more
7 update modes — append, overwrite, replace range, replace all, insert before/after, delete range
Media orchestration — 4-step insert pipeline with auto-rollback on failure
Whiteboard operations — create and update whiteboards via DSL for architecture diagrams, flowcharts, and mind maps
Cross-module search — unified search across documents, wiki, and spreadsheets

Create Documents

+create — Create a Lark Document

Create a new cloud document from Lark-flavored Markdown content. Documents are created in the user’s root folder by default, or you can specify a target folder, wiki node, or wiki space. The --folder-token, --wiki-node, and --wiki-space flags are mutually exclusive.

    # Create a simple document in root folder
    $ lark-cli docs +create --title "Weekly Report" --markdown "## Sprint 42\n### Highlights\n- Completed auth module\n- Deployed v2.1"
  

    # Create in a specific folder
    $ lark-cli docs +create --title "Design Doc" --folder-token "fldcnXXXX" --markdown "## Architecture\n\n### Overview\nMicroservices-based design..."
  

    # Create inside a wiki space
    $ lark-cli docs +create --title "API Reference" --wiki-space "7000000000000000000" --markdown "## Endpoints\n\n### GET /users\nReturns a list of users."
  

    # Create under a specific wiki node
    $ lark-cli docs +create --title "Onboarding Guide" --wiki-node "wikcnXXXX" --markdown "## Welcome\n\nThis guide covers setup and configuration."
  

    # Create in personal knowledge library
    $ lark-cli docs +create --title "Study Notes" --wiki-space my_library --markdown "## Notes\n\n- Key takeaway 1\n- Key takeaway 2"
  

Parameters

Parameter	Required	Description
`--markdown`	Yes	Lark-flavored Markdown content for the document body
`--title`	No	Document title (do not repeat as H1 in markdown)
`--folder-token`	No	Parent folder token (mutually exclusive with wiki flags)
`--wiki-node`	No	Wiki node token to create under
`--wiki-space`	No	Wiki space ID; use `my_library` for personal library

Returns: doc_id (document token), doc_url (browser link), and message (status). When created under a wiki, the URL may be in /wiki/... format — use doc_id for subsequent API calls.

Scope: docx:document:create

Identity: User or Bot. When using bot identity, grant the user full_access permission after creation.

Read Documents

+fetch — Fetch Document Content

Retrieve the content of a Lark document by its URL or token. Supports pagination for large documents with --offset and --limit.

    # Fetch entire document
    $ lark-cli docs +fetch --doc "docxXXXXXXXXXX"
  

    # Fetch with pagination (first 50 blocks)
    $ lark-cli docs +fetch --doc "docxXXXXXXXXXX" --offset 0 --limit 50
  

    # Fetch using a document URL
    $ lark-cli docs +fetch --doc "https://example.feishu.cn/docx/docxXXXXXXXXXX"
  

Parameter	Required	Description
`--doc`	Yes	Document URL or token
`--offset`	No	Pagination offset
`--limit`	No	Pagination limit (number of blocks to return)

Scope: docx:document:readonly

Update Documents

+update — Update a Lark Document (7 Modes)

Update an existing document using one of 7 update modes. Each mode serves a different editing pattern, from appending content to surgical text replacement. The --selection-with-ellipsis and --selection-by-title locators are mutually exclusive.

Append Mode

    # Append new content to the end of a document
    $ lark-cli docs +update --doc "docxXXX" --mode append --markdown "## New Section\n\nAdditional content appended here."
  

Overwrite Mode

    # Replace the entire document body
    $ lark-cli docs +update --doc "docxXXX" --mode overwrite --markdown "# Complete Replacement\n\nAll previous content is gone."
  

Replace Range Mode

    # Replace a specific section identified by start...end text
    $ lark-cli docs +update --doc "docxXXX" --mode replace_range --selection-with-ellipsis "old paragraph text...surrounding context" --markdown "Updated paragraph content"
  

Replace All Mode

    # Replace all occurrences of a text pattern
    $ lark-cli docs +update --doc "docxXXX" --mode replace_all --selection-with-ellipsis "v1.0..." --markdown "v2.0"
  

Insert Before / After Mode

    # Insert content before a section identified by title
    $ lark-cli docs +update --doc "docxXXX" --mode insert_before --selection-by-title "## Section 3" --markdown "## Section 2.5\n\nInserted before Section 3."
  

    # Insert content after a section
    $ lark-cli docs +update --doc "docxXXX" --mode insert_after --selection-by-title "## Conclusion" --markdown "## Appendix\n\nSupplementary data."
  

Delete Range Mode

    # Delete a specific text range (no --markdown needed)
    $ lark-cli docs +update --doc "docxXXX" --mode delete_range --selection-with-ellipsis "obsolete paragraph...end marker"
  

Rename Document

    # Update the document title (combine with any mode)
    $ lark-cli docs +update --doc "docxXXX" --mode append --markdown " " --new-title "Updated Document Title"
  

All Update Parameters

Parameter	Required	Description
`--doc`	Yes	Document URL or token
`--mode`	Yes	`append` \| `overwrite` \| `replace_range` \| `replace_all` \| `insert_before` \| `insert_after` \| `delete_range`
`--markdown`	Yes*	New content in Lark-flavored Markdown (* not required for `delete_range`)
`--selection-with-ellipsis`	Conditional	Content locator using `start...end` pattern (required for range/replace/insert/delete modes)
`--selection-by-title`	Conditional	Title locator, e.g. `## Section Name` (alternative to ellipsis selector)
`--new-title`	No	Also update the document title

Scope: docx:document:write_only, docx:document:readonly

Search Content

+search — Search Docs, Wiki & Spreadsheets

Unified search across cloud documents, wiki pages, and spreadsheets using the Search v2 API (POST /open-apis/search/v2/doc_wiki/search). Despite the endpoint name, results include spreadsheets (SHEET type) in addition to docs and wiki pages. Use this as a resource discovery entry point before switching to domain-specific commands.

    # Search for documents by keyword
    $ lark-cli docs +search --query "quarterly report"
  

    # Search with time-based filter
    $ lark-cli docs +search --query "product roadmap" --filter '{"open_time":{"start":"2026-01-01T00:00:00+08:00","end":"2026-03-30T23:59:59+08:00"}}'
  

    # Empty search (returns recently viewed documents)
    $ lark-cli docs +search
  

    # Paginate through results
    $ lark-cli docs +search --query "OKR" --page-token "next_page_token" --page-size 20
  

Parameter	Required	Description
`--query`	No	Search keyword (empty = recent documents)
`--filter`	No	JSON filter for type/owner/time conditions
`--page-size`	No	Results per page (default 15, max 20)
`--page-token`	No	Pagination token for next page

Scope: search:docs:read. Identity: User only (bot identity cannot perform searches).

Insert Media

+media-insert — Insert Images & Files (4-Step Orchestration)

Insert a local image or file at the end of a document. This command orchestrates a 4-step pipeline with automatic rollback on failure: (1) query document root block, (2) create a placeholder block, (3) upload the file, and (4) bind the uploaded file token to the block. For wiki URLs, a 5th step resolves the wiki node to the actual docx token first.

Maximum file size: 20 MB. Supports PNG, JPG, GIF, WebP, BMP images and general file attachments.

    # Insert an image with center alignment and caption
    $ lark-cli docs +media-insert --file ./diagram.png --doc "docxXXXXXX" --align center --caption "Architecture diagram"
  

    # Insert a file attachment
    $ lark-cli docs +media-insert --file ./report.pdf --doc "docxXXXXXX" --type file
  

    # Insert image into a wiki page (auto-resolves wiki token)
    $ lark-cli docs +media-insert --file ./screenshot.png --doc "https://example.feishu.cn/wiki/wikiXXXXXX"
  

Parameter	Required	Description
`--file`	Yes	Local file path (max 20 MB)
`--doc`	Yes	Document URL or document_id (docx only)
`--type`	No	`image` (default) or `file`
`--align`	No	`left`, `center`, or `right`
`--caption`	No	Image caption text

Scope: docs:document.media:upload, docx:document:write_only, docx:document:readonly

Download Media

+media-download — Download Document Media

Download media files or whiteboard thumbnails from documents. The extension is auto-detected from the content type (PNG, JPG, GIF, WebP, SVG, PDF, MP4, TXT).

    # Download a media file from a document
    $ lark-cli docs +media-download --token "boxXXXXXX" --output ./downloaded-image.png
  

    # Download a whiteboard as image
    $ lark-cli docs +media-download --token "wbXXXXXX" --output ./whiteboard.png --type whiteboard
  

    # Overwrite existing output file
    $ lark-cli docs +media-download --token "boxXXXXXX" --output ./image.png --overwrite
  

Parameter	Required	Description
`--token`	Yes	Resource token (file_token or whiteboard_id)
`--output`	Yes	Local save path
`--type`	No	`media` (default) or `whiteboard`
`--overwrite`	No	Overwrite existing output file (boolean)

Scope: docs:document.media:download

Whiteboard Operations

Creating & Updating Whiteboards

Whiteboards in Lark documents are created inline using the +create or +update commands with special Markdown syntax. To update whiteboard content, use the whiteboard-cli tool to parse DSL content and pipe it into the update command.

Create Blank Whiteboards

    # Create a document with a blank whiteboard
    $ lark-cli docs +create --title "Whiteboard Doc" --markdown '<whiteboard type="blank"></whiteboard>'
  

    # Create a document with multiple whiteboards
    $ lark-cli docs +create --title "Design Boards" --markdown '## Board 1\n<whiteboard type="blank"></whiteboard>\n## Board 2\n<whiteboard type="blank"></whiteboard>'
  

Update Whiteboard Content

    # Update a whiteboard using DSL via stdin
    $ whiteboard-cli render architecture.dsl | lark-cli docs +whiteboard-update --whiteboard-token "wbXXXXXX"
  

    # Overwrite existing whiteboard content
    $ whiteboard-cli render flowchart.dsl | lark-cli docs +whiteboard-update --whiteboard-token "wbXXXXXX" --overwrite
  

Parameter	Required	Description
`--whiteboard-token`	Yes	Whiteboard token (requires edit permission on the parent document)
`--idempotent-token`	No	Idempotency token (min 10 characters)
`--overwrite`	No	Delete all existing content before updating (default false)

Supported diagram types include architecture diagrams, flowcharts, org charts, mind maps, and Mermaid/PlantUML diagrams (auto-converted to Lark whiteboard format).

Wiki Integration

Handling Wiki URLs

Wiki pages in Feishu use a different URL format (feishu.cn/wiki/XXXXX) than regular documents. When working with wiki content, you need to resolve the wiki token to the actual document token first.

The +media-insert command handles this automatically (5-step orchestration). For other commands, resolve manually:

    # Resolve a wiki URL to get the actual document token
    $ lark-cli wiki spaces get_node --token "wikiXXXXXX"
  

    # Then use the resolved docx token for operations
    $ lark-cli docs +fetch --doc "docxYYYYYY"
  

The +create command supports direct wiki placement via --wiki-node or --wiki-space, so resolution is only needed for read/update operations on existing wiki pages.

Permissions

Required OAuth Scopes

Operation	Scope
Create documents	`docx:document:create`
Read documents	`docx:document:readonly`
Update documents	`docx:document:write_only`, `docx:document:readonly`
Search documents	`search:docs:read`
Upload media	`docs:document.media:upload`
Download media	`docs:document.media:download`

Command Reference

All Document Shortcut Commands

Shortcut	Description	Risk	Identity	Key Parameters
`+create`	Create a Lark document from Markdown	Write	User, Bot	--title, --markdown, --folder-token, --wiki-space, --wiki-node
`+fetch`	Fetch document content	Read	User, Bot	--doc, --offset, --limit
`+update`	Update document (7 modes)	Write	User, Bot	--doc, --mode, --markdown, --selection-with-ellipsis, --selection-by-title, --new-title
`+search`	Search docs, wiki, and spreadsheets	Read	User only	--query, --filter, --page-size, --page-token
`+media-insert`	Insert local image/file into document	Write	User, Bot	--file, --doc, --type, --align, --caption
`+media-download`	Download document media or whiteboard	Read	User, Bot	--token, --output, --type, --overwrite