{"id":47702228,"url":"https://github.com/cliff-byte/feishu-docs-cli","last_synced_at":"2026-05-09T12:01:36.975Z","repository":{"id":343994002,"uuid":"1177586702","full_name":"cliff-byte/feishu-docs-cli","owner":"cliff-byte","description":"A lightweight CLI tool for Feishu/Lark document and wiki management, designed for Agentic Coding scenarios","archived":false,"fork":false,"pushed_at":"2026-05-09T10:06:54.000Z","size":7465,"stargazers_count":6,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-09T11:35:48.782Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cliff-byte.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-03-10T07:01:12.000Z","updated_at":"2026-05-09T10:06:58.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/cliff-byte/feishu-docs-cli","commit_stats":null,"previous_names":["cliff-byte/feishu-docs-cli"],"tags_count":16,"template":false,"template_full_name":null,"purl":"pkg:github/cliff-byte/feishu-docs-cli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cliff-byte%2Ffeishu-docs-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cliff-byte%2Ffeishu-docs-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cliff-byte%2Ffeishu-docs-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cliff-byte%2Ffeishu-docs-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cliff-byte","download_url":"https://codeload.github.com/cliff-byte/feishu-docs-cli/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cliff-byte%2Ffeishu-docs-cli/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32818397,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-08T08:22:46.396Z","status":"online","status_checked_at":"2026-05-09T02:00:06.633Z","response_time":123,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-02T17:31:35.009Z","updated_at":"2026-05-09T12:01:36.964Z","avatar_url":"https://github.com/cliff-byte.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# feishu-docs-cli\n\n[![License](https://img.shields.io/badge/License-MIT-yellow)](./LICENSE) [![Node](https://img.shields.io/badge/node-%3E%3D18.3.0-blue)](https://nodejs.org) [![npm](https://img.shields.io/npm/v/feishu-docs-cli)](https://www.npmjs.com/package/feishu-docs-cli) [![Zero Dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)](./package.json)\n\n[中文文档](./README.zh.md) | English\n\nCLI tool for AI Agents to read/write Feishu (Lark) docs via shell commands.\n\n## Project Status\n\n\u003e **Note**: The official [lark-cli](https://github.com/larksuite/cli) has been released by the Lark/Feishu team (2026). It covers a much broader range of Feishu APIs (IM, calendar, tasks, contacts, bitable, etc.). We believe the official tool will continue to improve, so **this project will slow down on new feature development**. Existing functionality will be maintained but no major additions are planned.\n\u003e\n\u003e If you need full Feishu API coverage, use [lark-cli](https://github.com/larksuite/cli). If you primarily work with **documents and knowledge bases** and need clean Markdown I/O, feishu-docs-cli still offers a better experience in that specific area.\n\n## Comparison with lark-cli\n\nBased on real-world testing against the same knowledge base (2026-03-29):\n\n| Capability | feishu-docs-cli | lark-cli (official) |\n|------------|-----------------|---------------------|\n| **Read as Markdown** | Standard Markdown — tables, lists, code blocks render correctly | Returns JSON with `\u003clark-table\u003e` custom HTML tags, not standard Markdown |\n| **Knowledge base tree** | `tree` command — one call, full recursive tree | No equivalent — must call `get_node` per node |\n| **Batch read wiki** | `cat` — recursively reads all child docs | No equivalent |\n| **Create in wiki** | `--wiki \u003cspace\u003e --parent \u003cnode\u003e` — supports parent node placement | `--wiki-space` and `--wiki-node` are mutually exclusive |\n| **Update docs** | Accepts file path (`--body file.md`), auto-backup before overwrite | Inline `--markdown` only, `--mode` required |\n| **Search** | `search \"keyword\"` — one step | Requires separate scope authorization |\n| **Share / permissions** | `share list/add/remove/update/set` — fully wrapped | No wrapper — requires raw API calls |\n| **JSON output** | Clean, pipe-friendly `--json` | Mixes progress text (`[page 1] fetching...`) into stdout |\n| **Error messages** | Chinese messages with recovery hints, missing scope auto-detection | English errors, manual scope lookup |\n| **API coverage** | Documents, wiki, drive, search, permissions | **Full platform** — IM, calendar, tasks, contacts, bitable, mail, video conference, etc. |\n| **Dependencies** | Zero runtime deps (Node.js built-ins only) | Go binary |\n| **Cold start** | ~0.5s (Node.js) | ~0.1s (Go) |\n\n**In short**: feishu-docs-cli is purpose-built for **document workflows** — clean Markdown I/O, recursive wiki browsing, and write safety. lark-cli is a comprehensive platform CLI with broader API coverage. \n## Features\n\n- **Read** documents as Markdown (images downloaded to local files), raw text, or original Block JSON\n- **Create** documents in knowledge bases or cloud folders\n- **Update** documents with overwrite or append mode (auto-batch for large content)\n- **Delete** documents (move to recycle bin)\n- **Info** — view document metadata (title, type, URL, revision)\n- **Browse** knowledge base structure (spaces, tree, cat)\n- **Search** documents by keyword\n- **Share** — manage collaborators (list, add, set public mode)\n- **List** files in cloud folders\n- Written in TypeScript with strict mode\n- Zero runtime dependencies — uses native `fetch` for all API calls\n- Agent-friendly output — pure text or JSON, no interactive UI\n\n## Install\n\n```bash\nnpm install -g feishu-docs-cli\n```\n\nOr use directly with npx:\n\n```bash\nnpx feishu-docs-cli read \u003curl\u003e\n```\n\nYou can also install from GitHub:\n\n```bash\nnpm install -g github:cliff-byte/feishu-docs-cli\n```\n\nRequires Node.js \u003e= 18.3.\n\n## Setup\n\n### 1. Create a Feishu App\n\n1. Go to [Feishu Open Platform](https://open.feishu.cn/app) (or [Lark Developer](https://open.larksuite.com/app) for international)\n2. Click **Create Custom App**, fill in the app name and description\n3. After creation, go to the app's **Credentials \u0026 Basic Info** page. Copy the **App ID** (`cli_xxx`) and **App Secret** — you'll need them for environment variables\n4. Go to **Permissions \u0026 Scopes**, search and add the following scopes:\n\n   **Base scopes** (no admin review needed — requested automatically during `feishu-docs login`):\n\n   | Scope | Description |\n   |-------|-------------|\n   | `offline_access` | Token auto-refresh (enables refresh_token for 7-day validity) |\n   | `wiki:wiki` | Knowledge base read/write |\n   | `docx:document` | Document read/write |\n   | `docx:document.block:convert` | Markdown to block conversion (create/update) |\n   | `sheets:spreadsheet:readonly` | Embedded spreadsheet read (read command) |\n   | `board:whiteboard:node:read` | Whiteboard export as image (read command) |\n   | `bitable:app:readonly` | Embedded bitable/table read (read command) |\n   | `docs:document.media:download` | Download images and attachments from documents |\n\n   **Additional scopes** are requested reactively — when an API call needs a scope you haven't authorized, the CLI detects this from the API error response and prompts you. Common ones:\n\n   | Scope | Description |\n   |-------|-------------|\n   | `drive:drive` | Cloud file management (ls, delete, share, mv, cp, mkdir) |\n   | `contact:contact.base:readonly` | User lookup by email/phone |\n   | `drive:drive.search:readonly` | Document search |\n\n5. Go to **Security Settings**, add the OAuth callback URL to the **Redirect URLs** allowlist:\n   - Default: `http://127.0.0.1:3456/callback`\n   - This must match exactly what you use during `feishu-docs login`\n\n6. **Publish the app version**: Go to **App Release** → **Create Version** → Submit for review → Approve (self-built apps in your org are usually auto-approved)\n\n\u003e **Note**: For tenant-level access (e.g., CI/CD), the app must be granted access to specific docs or knowledge bases. Add the app as a collaborator, or use the admin console to authorize document scope.\n\n### 2. Set Environment Variables\n\n```bash\nexport FEISHU_APP_ID=\"cli_xxx\"        # From step 3 above\nexport FEISHU_APP_SECRET=\"xxx\"         # From step 3 above\n```\n\n### 3. Login (for user-level access)\n\nUser-level access enables personal docs, search, and collaboration features.\n\n```bash\nfeishu-docs login\n```\n\nThis opens a browser for OAuth authorization and saves the encrypted token to `~/.feishu-docs/auth.json`.\n\nIf your app's registered redirect URL differs from the default (`http://127.0.0.1:3456/callback`), pass the exact same value:\n\n```bash\n# Match the exact redirect URI registered in Feishu Open Platform\nfeishu-docs login --redirect-uri http://127.0.0.1:3456/callback\n\n# Or change only the port and keep the default localhost path\nfeishu-docs login --port 4567\n```\n\n### CI / Container Environments\n\nIn CI pipelines, Docker containers, or headless servers where interactive OAuth login is not possible, use the `FEISHU_USER_TOKEN` environment variable instead of `feishu-docs login`:\n\n```bash\nexport FEISHU_APP_ID=\"cli_xxx\"\nexport FEISHU_APP_SECRET=\"xxx\"\nexport FEISHU_USER_TOKEN=\"u-xxx\"   # User access token from Feishu API\n```\n\nWith these three variables set, all commands work without `feishu-docs login`. The token is used directly without local encryption or storage.\n\n**Important:**\n- `FEISHU_USER_TOKEN` has no auto-refresh -- you are responsible for rotating it before expiry\n- Do NOT use `feishu-docs login` in containers -- it spawns a local HTTP server and attempts to open a browser\n- For tenant-only access (no user context), `FEISHU_APP_ID` and `FEISHU_APP_SECRET` are sufficient\n\n## Usage\n\n### Read\n\n```bash\n# Read document as Markdown (images auto-downloaded to ~/.feishu-docs/images/)\nfeishu-docs read https://xxx.feishu.cn/wiki/wikcnXXX\n\n# Read by token\nfeishu-docs read wikcnXXX\n\n# Raw Block JSON (lossless)\nfeishu-docs read \u003curl\u003e --blocks\n\n# Plain text only\nfeishu-docs read \u003curl\u003e --raw\n\n# With metadata header\nfeishu-docs read \u003curl\u003e --with-meta\n```\n\nImages in documents are automatically downloaded to `~/.feishu-docs/images/` and referenced as local file paths in the Markdown output. Cached images are reused for 30 days.\n\n### Knowledge Base\n\n```bash\n# List all knowledge bases\nfeishu-docs spaces\n\n# Show node tree\nfeishu-docs tree \u003cspace_id\u003e\nfeishu-docs tree \u003cspace_id\u003e --depth 2\n\n# Recursively read all documents\nfeishu-docs cat \u003cspace_id\u003e --max-docs 20\nfeishu-docs cat \u003cspace_id\u003e --node \u003ctoken\u003e --title-only\n```\n\n### Search\n\n```bash\nfeishu-docs search \"API design\" --type docx --limit 10\n```\n\nRequires user access token. Use `feishu-docs login` first.\n\n### Create\n\n```bash\n# In knowledge base\nfeishu-docs create \"API Docs\" --wiki \u003cspace_id\u003e --body ./api.md\n\n# In cloud folder\nfeishu-docs create \"API Docs\" --folder \u003cfolder_token\u003e --body ./api.md\n\n# Empty document\nfeishu-docs create \"API Docs\"\n\n# From stdin\ncat design.md | feishu-docs create \"Design\" --wiki \u003cspace_id\u003e --body -\n```\n\n### Update\n\n```bash\n# Overwrite (backs up first)\nfeishu-docs update \u003curl\u003e --body ./updated.md\n\n# Append\nfeishu-docs update \u003curl\u003e --body ./extra.md --append\n\n# From stdin\necho \"## New Section\" | feishu-docs update \u003curl\u003e --body - --append\n\n# Restore from backup\nfeishu-docs update \u003curl\u003e --restore ~/.feishu-docs/backups/xxx.json\n```\n\n### Delete\n\n```bash\nfeishu-docs delete \u003curl\u003e --confirm\n```\n\nMoves document to recycle bin (recoverable for 30 days).\n\n### Info\n\n```bash\nfeishu-docs info \u003curl|token\u003e\nfeishu-docs info \u003curl\u003e --json\n```\n\n### List Files\n\n```bash\n# List root folder\nfeishu-docs ls\n\n# List specific folder\nfeishu-docs ls \u003cfolder_token\u003e\n\n# Filter by type\nfeishu-docs ls --type docx --limit 20\n```\n\n### File Operations\n\n```bash\n# Move file to a folder\nfeishu-docs mv \u003curl|token\u003e \u003ctarget_folder_token\u003e\n\n# Copy file (auto-names as \"Title - 副本\")\nfeishu-docs cp \u003curl|token\u003e \u003ctarget_folder_token\u003e\n\n# Copy with custom name\nfeishu-docs cp \u003curl|token\u003e \u003ctarget_folder_token\u003e --name \"My Copy\"\n\n# Create a folder\nfeishu-docs mkdir \"New Folder\" --parent \u003cparent_folder_token\u003e\n```\n\n### Share\n\n```bash\n# List collaborators\nfeishu-docs share list \u003curl\u003e\n\n# Add collaborator\nfeishu-docs share add \u003curl\u003e user@example.com --role view\nfeishu-docs share add \u003curl\u003e ou_xxx --role edit\n\n# Remove collaborator\nfeishu-docs share remove \u003curl\u003e user@example.com\n\n# Update collaborator role\nfeishu-docs share update \u003curl\u003e ou_xxx --role manage\n\n# Set public sharing mode\nfeishu-docs share set \u003curl\u003e --public tenant          # org-wide readable\nfeishu-docs share set \u003curl\u003e --public tenant:edit      # org-wide editable\nfeishu-docs share set \u003curl\u003e --public open             # anyone readable\nfeishu-docs share set \u003curl\u003e --public closed           # disable link sharing\n```\n\nRoles: `view`, `edit`, `manage`. Member types are auto-detected (email, openid, unionid, openchat, userid).\n\n### Auth\n\n```bash\nfeishu-docs login          # OAuth login (default callback: http://127.0.0.1:3456/callback)\nfeishu-docs logout         # Clear saved credentials\nfeishu-docs whoami         # Show current auth status\n```\n\n## Global Options\n\n| Option | Description |\n|--------|-------------|\n| `--auth \u003cuser\\|tenant\\|auto\u003e` | Auth mode (default: auto) |\n| `--json` | Output JSON format |\n| `--lark` | Use Lark (international) domain |\n| `--help` | Show help |\n| `-v, --version` | Show version |\n\n## Auth Modes\n\n| Mode | Token Type | Use Case |\n|------|-----------|----------|\n| `user` | user_access_token | Personal docs, collaboration, search |\n| `tenant` | tenant_access_token | App-managed docs, CI/CD |\n| `auto` | Best available | Default — tries user first, falls back to tenant |\n\n## AI Agent Integration\n\n### Claude Code\n\nInstall the skill via [skills.sh](https://skills.sh) (works with Claude Code, Cursor, Codex, and 37+ agents):\n\n```bash\nnpx skills add cliff-byte/feishu-docs-cli\n```\n\nOr install directly via the CLI:\n\n```bash\nfeishu-docs install-skill\n```\n\nAfter installation, use `/feishu-docs` in Claude Code to activate the skill.\n\n### Other Agents\n\nAdd these instructions to your agent's system prompt or configuration:\n\n```\nRead Feishu docs:    feishu-docs read \u003curl\u003e\nSearch docs:         feishu-docs search \u003ckeyword\u003e\nBrowse wiki:         feishu-docs tree \u003cspace_id\u003e\nBatch read:          feishu-docs cat \u003cspace_id\u003e --max-docs 10\nCreate doc:          feishu-docs create \u003ctitle\u003e --wiki \u003cspace_id\u003e --body \u003cfile\u003e\nUpdate doc:          feishu-docs update \u003curl\u003e --body \u003cfile\u003e\nUse --json for structured output. Run feishu-docs --help for all commands.\n```\n\n### Programmatic Usage\n\nAll commands output to stdout (results) and stderr (errors/warnings). Exit codes:\n\n| Code | Meaning |\n|------|---------|\n| 0 | Success |\n| 1 | Invalid args |\n| 2 | Auth failure |\n| 3 | API error |\n\nUse `--json` for structured output that agents can parse.\n\n## Write Safety\n\nOverwrite operations (`update` without `--append`) automatically:\n\n1. **Back up** current document to `~/.feishu-docs/backups/`\n2. **Clear** then **rewrite** the document\n3. **Auto-recover** from backup if write fails\n4. **Rotate** backups (keeps last 10)\n\nFeishu also maintains version history — you can always roll back in the Feishu client.\n\n## Development\n\n```bash\ngit clone https://github.com/cliff-byte/feishu-docs-cli.git\ncd feishu-docs-cli\nnpm install\n\n# Type check\nnpm run build:check\n\n# Build (outputs to dist/)\nnpm run build\n\n# Run tests\nnpm test\n\n# Run CLI from source\nnpm run build \u0026\u0026 node bin/feishu-docs.js --help\n```\n\n### Project Structure\n\n```\nsrc/\n  types/          # Shared TypeScript type definitions\n  commands/       # CLI command handlers\n  services/       # API service layer\n  parser/         # Block-to-Markdown parser\n  utils/          # Validation, error handling, URL parsing\ntest/             # Unit tests (node:test)\nbin/              # CLI entry point (JS shim → dist/)\ndist/             # Compiled output (git-ignored)\n```\n\n## Roadmap\n\n- [x] Feishu cloud document operations (read, create, update, delete, info)\n- [x] Knowledge base operations (spaces, tree, cat, wiki management, share, search)\n- [x] Quality hardening — 456 tests, retry logic, error recovery, dead code cleanup\n\n\u003e Bitable and Sheets operations are not planned. For those, use the official [lark-cli](https://github.com/larksuite/cli).\n\n## Mermaid Diagrams\n\nfeishu-docs-cli and lark-cli handle Mermaid differently when writing:\n\n| | feishu-docs-cli | lark-cli (official) |\n|---|---|---|\n| **Write** | Stored as `` ```mermaid `` code block (block_type 14) | Converted to whiteboard/board (block_type 43) via Lark MCP |\n| **Read back own output** | Returns original Mermaid code — lossless round-trip | Returns whiteboard node graph (shapes, coordinates, connectors) — cannot recover Mermaid source |\n| **Read native Mermaid** | Both tools can read Mermaid code blocks written natively in Feishu — no issue here |\n| **Human readability** | Code block in document — not visually rendered (Feishu supports \"text diagram\" blocks but the Open API cannot create them) | Renders as interactive diagram immediately |\n| **Best for** | AI agent workflows — Mermaid survives read/write round-trips | Human consumption — visual diagrams, but one-way (write-only) |\n\n**Why this trade-off?** Feishu has a native \"text diagram\" block that renders Mermaid visually, but the Open API's Convert endpoint does not support creating it — Mermaid is treated as a plain code block. lark-cli works around this by converting Mermaid to a whiteboard (board) via the Lark MCP protocol, which produces a visual result but loses the Mermaid source code. We chose to preserve the code block so AI agents can reliably read and modify diagrams.\n\n## Limitations\n\n- **Supported**: docx (new documents)\n- **Embedded content**: sheet (rendered as table), bitable (rendered as table), board/whiteboard (exported as image)\n- **Link only**: mindnote\n- **Not supported**: doc (legacy format)\n- Markdown conversion is lossy (colors, merged cells, layouts are dropped). Use `--blocks` for lossless JSON.\n- Image read downloads to local files (`~/.feishu-docs/images/`) with 30-day cache.\n- Local markdown images are uploaded on write when they appear as standalone block-level images, e.g. `![screenshot](./images/demo.png)`. Inline images, images inside lists/tables, and image paths outside the markdown file's directory tree are not supported.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcliff-byte%2Ffeishu-docs-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcliff-byte%2Ffeishu-docs-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcliff-byte%2Ffeishu-docs-cli/lists"}