Feishu Docs CLI

feishu-docs is a CLI tool that lets you read and write Feishu (Lark) cloud documents directly from the terminal. All output goes to stdout as plain text or JSON — designed for agent consumption.

Prerequisites

Before using any command, verify the environment is ready:

feishu-docs whoami

If this fails with an auth error:

Ensure FEISHU_APP_ID and FEISHU_APP_SECRET environment variables are set
For user-level features (search, personal docs), the user needs to run feishu-docs login interactively in their terminal — you cannot do this for them
Tenant (app) mode works without login but only accesses docs the app has been granted permission to

Reading Documents

Read a document by URL or token. Output is Markdown by default.

feishu-docs read <url|token>
feishu-docs read <url> --blocks        # Lossless Block JSON
feishu-docs read <url> --raw           # Plain text
feishu-docs read <url> --with-meta     # Prepend title/URL/revision metadata

Accepts full Feishu/Lark URLs or raw tokens (e.g., wikcnXXX, doxcnXXX). The URL format is automatically detected — wiki pages, docx, sheets, and bitable links all work.

Markdown conversion is lossy (colors, merged cells, complex layouts are dropped). When fidelity matters, use --blocks to get the raw Block JSON.

Browsing Knowledge Bases

Discover what's available before reading:

feishu-docs spaces                         # List all accessible wiki spaces
feishu-docs tree <space_id> --depth 3      # Show document tree structure
feishu-docs cat <space_id> --max-docs 20   # Read all docs recursively
feishu-docs cat <space_id> --title-only    # Just list titles
feishu-docs cat <space_id> --node <token>  # Start from a specific node

spaces returns space IDs and names. Use a space_id with tree to understand the structure, then read individual documents or cat to batch-read.

Searching

feishu-docs search "keyword" --type docx --limit 10

Search requires a user access token (feishu-docs login). It will not work with tenant-only auth.

Creating Documents

# Create in a wiki space
feishu-docs create "Title" --wiki <space_id> --body ./content.md

# Create in a cloud folder
feishu-docs create "Title" --folder <folder_token> --body ./content.md

# Create empty document (returns URL)
feishu-docs create "Title"

# Pipe content from stdin
echo "# Hello" | feishu-docs create "Title" --wiki <space_id> --body -

The --body flag accepts a file path or - for stdin. Content is Markdown — the API converts it to Feishu blocks server-side.

When creating under a wiki node, use --wiki <space_id> --parent <node_token> to place it under a specific parent.

Updating Documents

# Overwrite entire document (auto-backs up first)
feishu-docs update <url> --body ./updated.md

# Append to end of document
feishu-docs update <url> --body ./extra.md --append

# Pipe from stdin
echo "## New Section" | feishu-docs update <url> --body - --append

Overwrite mode automatically backs up the current document to ~/.feishu-docs/backups/ before writing. If the write fails, it auto-recovers from the backup.

To restore a previous version:

feishu-docs update <url> --restore ~/.feishu-docs/backups/<backup-file>.json

Deleting Documents

feishu-docs delete <url> --confirm

Moves to recycle bin (recoverable for 30 days). The --confirm flag is required.

Document Info

feishu-docs info <url|token>          # Human-readable metadata
feishu-docs info <url> --json         # Structured JSON output

Returns title, document type, URL, owner, creation time, and revision number.

Listing Cloud Files

feishu-docs ls                             # Root folder
feishu-docs ls <folder_token>              # Specific folder
feishu-docs ls --type docx --limit 20      # Filter by type

Sharing & Permissions

feishu-docs share list <url>                          # View collaborators
feishu-docs share add <url> user@example.com --role view
feishu-docs share add <url> ou_xxx --role edit
feishu-docs share set <url> --public tenant            # Org-wide readable
feishu-docs share set <url> --public tenant:edit        # Org-wide editable
feishu-docs share set <url> --public open               # Internet-accessible
feishu-docs share set <url> --public closed             # Disable link sharing

Roles: view, edit, manage. Member types (email, openid, unionid, userid) are auto-detected.

Wiki Management

feishu-docs wiki create-space <name>
feishu-docs wiki add-member <space_id> <member>
feishu-docs wiki remove-member <space_id> <member>
feishu-docs wiki rename <url> --title <new_title>
feishu-docs wiki move <url> --to <space_id>
feishu-docs wiki copy <url> --to <space_id>

Global Options

Every command accepts these flags:

Flag	Effect
`--auth user`	Force user token (personal docs, search)
`--auth tenant`	Force app token (CI/CD, shared docs)
`--json`	Output structured JSON instead of text
`--lark`	Use Lark (international) domain

Default auth mode is auto — tries user token first, falls back to tenant.

Common Workflows

Research a wiki space: spaces → pick a space_id → tree <space_id> → read specific docs

Write a report to wiki: Write markdown locally → create "Title" --wiki <space_id> --body ./report.md

Update existing doc: read <url> to see current content → edit locally → update <url> --body ./updated.md

Batch extract: cat <space_id> --max-docs 50 to dump all docs as markdown for analysis

Limitations

Only docx (new document format) is fully supported for read/write
Legacy doc format is not supported
Images cannot be written; read returns temporary URLs valid ~24 hours
Markdown conversion is lossy — use --blocks for lossless JSON when precision matters
Search requires user-level auth (run feishu-docs login first)