feishu-docx
๐ Feishu/Lark DocsใSheetใBitable <-> Markdown | AI Agent-friendly knowledge base exporter and writer with OAuth 2.0, CLI, TUI & Claude Skills support - ้ฃไนฆๆๆกฃ <ๅๅ ฅ/ๅฏผๅบ> Markdown | AI Agent ๅๅฅฝๅๅฏผๅบ-ๅๅ ฅๅทฅๅ ท
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Check it deeper on your machine
It has changed since its scan on 11 Nov 2026.
As a Claude Code plugin, install it and then ask Claude Code:
/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/leemysw/feishu-docx with scanskillsafety
Or from a terminal, clone it and run it:
git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/leemysw/feishu-docx'
It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.
Badge for your README
Markdown
[](/listings/leemysw--feishu-docx)HTML
<a href="/listings/leemysw--feishu-docx"><img src="/api/listings/leemysw--feishu-docx/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
These steps run a script from the network that findsafeskills does not scan.
Install
**Recommended: `uv tool install`** (isolated, no conflicts with system Python)
uv tool install feishu-docx
Optional features are installed separately to keep the core package lightweight:
# PDF export: --pdf, --pdf-template, --pdf-logo, syntax highlighting uv tool install 'feishu-docx[pdf]' # Browser-based export: export-browser uv tool install 'feishu-docx[browser]' playwright install chromium
Or run directly without installing:
uvx feishu-docx export "https://my.feishu.cn/wiki/xxx"
If you don't have `uv` yet: `curl -LsSf https://astral.sh/uv/install.sh | sh`
**Alternative: `pip install`** (works inside a virtual environment or with `--break-system-packages`)
pip install feishu-docx
Optional extras also work with `pip`:
pip install 'feishu-docx[pdf]' pip install 'feishu-docx[browser]' playwright install chromium
> Quote extras such as `'feishu-docx[pdf]'` in shells like zsh, otherwise the `[]` may be treated as a glob pattern.
> โ ๏ธ `pip install` outside a virtual environment may fail with `externally-managed-environment` on modern Linux/macOS (PEP 668). Use a virtual environment or `uv tool install` instead.
Configure and Export
# Configure credentials (one-time) feishu-docx config set --app-id YOUR_APP_ID --app-secret YOUR_APP_SECRET # Export! (auto-obtains tenant_access_token, no OAuth needed) feishu-docx export "https://my.feishu.cn/wiki/KUIJwaBuGiwaSIkkKJ6cfVY8nSg" # Create a Feishu doc directly from a WeChat article feishu-docx create --url "https://mp.weixin.qq.com/s/xxxxx" # Manage app cloud-space documents feishu-docx drive ls --type docx # Optional: Use OAuth mode for user-level permissions # feishu-docx config set --auth-mode oauth && feishu-docx auth
---
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md ยท README ยท 442 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- <div align="center">
- <img src="https://raw.githubusercontent.com/leemysw/feishu-docx/main/docs/icon.png" alt="feishu-docx" width="128">
- # feishu-docx
- <p align="center">
- <em>Feishu knowledge base export, writing, and cloud-space management tool with Markdown, WeChat import, CLI, TUI, and OAuth 2.0</em><br>
- </p>
- [](https://badge.fury.io/py/feishu-docx)
- [](https://www.python.org/downloads/)
- [](https://opensource.org/licenses/MIT)
- <p align="center">
- <a href="https://github.com/leemysw/feishu-docx/blob/main/README_zh.md">ไธญๆ</a> | <strong>English</strong>
- </p>
- </div>
- <div align="center">
- <img src="https://raw.githubusercontent.com/leemysw/feishu-docx/main/docs/tui.png" alt="feishu-docx TUI" width="90%">
- </div>
- ---
- ## ๐ Recent Updates (v0.2.8)
- - PDF table line breaks and inline code combined with bold, italic, or strikethrough now render correctly, while other raw HTML remains escaped ([#37](https://github.com/leemysw/feishu-docx/issues/37))
- - Card-view links retain their titles and destinations; encoded URLs are preserved correctly
- - Refreshed project icon and added public-document Markdown/PDF end-to-end regression coverage
- Upgrade with `pip install --upgrade "feishu-docx[pdf]"` for PDF export, or `uv tool upgrade feishu-docx` for an existing uv tool installation.
- ---
- ## ๐ฏ Why feishu-docx?
- **Let AI Agents read, write, and manage your Feishu/Lark knowledge base.**
- - ๐ค **Built for AI** โ Works seamlessly with Claude/GPT Skills for document retrieval
- - ๐ **Full Coverage** โ Documents, Spreadsheets, Bitables, Wiki nodes, and WeChat articles
- - โ๏ธ **Write Back Support** โ Create docs, append content, and update specific blocks
- - โ๏ธ **Cloud-Space Management** โ List files, delete files, manage permissions, clear files safely
- - ๐ **Authentication** โ One-time auth, automatic token refresh
- - ๐จ **Dual Interface** โ CLI + Beautiful TUI (Textual-based)
- - ๐ฆ **Easy Install** โ `uv tool install feishu-docx` or `pip install feishu-docx`
- ---
- ## โก Quick Start (30 seconds)
- ### Install
- **Recommended: `uv tool install`** (isolated, no conflicts with system Python)
- ```bash
- uv tool install feishu-docx
- ```
- Optional features are installed separately to keep the core package lightweight:
- ```bash
- # PDF export: --pdf, --pdf-template, --pdf-logo, syntax highlighting
- uv tool install 'feishu-docx[pdf]'
- # Browser-based export: export-browser
- uv tool install 'feishu-docx[browser]'
- playwright install chromium
- ```
- Or run directly without installing:
- ```bash
- uvx feishu-docx export "https://my.feishu.cn/wiki/xxx"
- ```
- If you don't have `uv` yet: `curl -LsSf https://astral.sh/uv/install.sh | sh`
- **Alternative: `pip install`** (works inside a virtual environment or with `--break-system-packages`)
- ```bash
- pip install feishu-docx
- ```
- Optional extras also work with `pip`:
- ```bash
- pip install 'feishu-docx[pdf]'
- pip install 'feishu-docx[browser]'
- playwright install chromium
- ```
- > Quote extras such as `'feishu-docx[pdf]'` in shells like zsh, otherwise the `[]` may be treated as a glob pattern.
- > โ ๏ธ `pip install` outside a virtual environment may fail with `externally-managed-environment` on modern Linux/macOS (PEP 668). Use a virtual environment or `uv tool install` instead.
- ### Configure and Export
- ```bash
- # Configure credentials (one-time)
- feishu-docx config set --app-id YOUR_APP_ID --app-secret YOUR_APP_SECRET
- # Export! (auto-obtains tenant_access_token, no OAuth needed)
- feishu-docx export "https://my.feishu.cn/wiki/KUIJwaBuGiwaSIkkKJ6cfVY8nSg"
- # Create a Feishu doc directly from a WeChat article
- feishu-docx create --url "https://mp.weixin.qq.com/s/xxxxx"
- # Manage app cloud-space documents
- feishu-docx drive ls --type docx
- # Optional: Use OAuth mode for user-level permissions
- # feishu-docx config set --auth-mode oauth && feishu-docx auth
- ```
- ---
- ## ๐ค Skills Support
- **Enable Agent to access your Feishu knowledge base directly!**
- This project includes a Claude Skill at `.skills/feishu-docx/SKILL.md`.
- Supports OpenCode, Claude Code, Codex, Cursor, and more.
- Copy this Skill to your agent project, and Claude can:
- - ๐ Read Feishu knowledge base as context
- - ๐ Search and reference internal documents
- - ๐ Create docs, append content, and update specific blocks
- ---
- ## โจ Features
- | Feature | Description |
- |-------------------------|-------------------------------------------------|
- | ๐ Document Export | Docx โ Markdown with formatting, images, tables |
- | ๐ Spreadsheet Export | Sheet โ Markdown tables, with rich-text cells and display/formula modes |
- | ๐ Bitable Export | Multidimensional tables โ Markdown |
- | ๐ Wiki Export | Auto-resolve wiki nodes |
- | ๐๏ธ Wiki Batch Export | Recursively export entire wiki space with hierarchy |
- | โ๏ธ Document Writing | Create docs, append Markdown, update specific blocks |
- | ๐ฐ WeChat Import/Export | Export WeChat articles or create Feishu docs from them |
- | ๐ Browser-Based Export | Export public docs or docs accessible in the current browser session, with local assets |
- | โ๏ธ Drive Management | List files, delete files, manage permissions, clear files |
- | ๐๏ธ Database Schema | Export APaaS database structure to Markdown |
- | ๐งท Local Asset Download | Images and attachments saved locally with relative paths |
- | ๐จ๏ธ PDF Export | Generate branded PDF with WeasyPrint, custom CSS templates |
- | ๐ Auth | Auto tenant_access_token (recommended) or OAuth 2.0 |
- | ๐จ Beautiful TUI | Terminal UI powered by Textual |
- ### โ Supported Blocks
- This tool currently supports exporting the following Feishu/Lark document components:
- | Category | Features | Status | Notes |
- |----------------|----------------------------------------------------------------|--------|------------------------------------------|
- | **Basic Text** | Headings, Paragraphs, Lists, Tasks (Todo), Code Blocks, Quotes | โ | Fully Supported |
- | **Formatting** | Bold, Italic, Strikethrough, Underline, Links, @Mentions | โ | Fully Supported |
- | **Layout** | Columns, Callouts, Dividers | โ | Fully Supported |
- | **Tables** | Native Tables | โ | Export to Markdown/HTML |
- | **Media** | Images, Drawing Boards | โ | Drawing boards exported as images |
- | **Embedded** | Spreadsheets (Sheets), Bitable | โ | Sheets support rich-text cells and display/formula modes |
- | **Special** | Synced Blocks, Add-ons Blocks | โ | Synced blocks support same-document and cross-document references |
- | **Files** | Attachments | โ | Local download when possible, temp link fallback |
- ---
- ## ๐ Usage
- ### Use Cases
- - Export Feishu docs, Sheets, Bitables, and Wiki nodes to Markdown
- - Export a WeChat article to Markdown
- - Create a Feishu doc directly from a WeChat article URL
- - Create, append, or update Feishu document content
- - Manage files and permissions in app cloud space or personal cloud space
- ### CLI
- `export-browser` requires Playwright.
- If you installed via `uv tool install`, install the browser extra:
- ```bash
- uv tool install 'feishu-docx[browser]'
- playwright install chromium
- ```
- If you are working inside a virtual environment:
- ```bash
- pip install 'feishu-docx[browser]'
- playwright install chromium
- ```
- ```bash
- # Export single document to specific directory
- feishu-docx export "https://xxx.feishu.cn/docx/xxx" -o ./docs
- # Choose display values or formulas for Sheets (affects Sheet and embedded Sheet only)
- feishu-docx export "https://xxx.feishu.cn/wiki/xxx" --table md --sheet-value-mode display
- feishu-docx export "https://xxx.feishu.cn/wiki/xxx" --table md --sheet-value-mode formula
- # Export a public or browser-readable doc in a real browser session
- feishu-docx export-browser "https://xxx.larkoffice.com/wiki/xxx" -o ./browser_docs
- # Export with existing Playwright storage state
- feishu-docx export-browser "https://xxx.larkoffice.com/wiki/xxx" --storage-state ./storage_state.json
- # Batch export entire wiki space (preserves hierarchy)
- feishu-docx export-wiki-space <space_id_or_url> -o ./wiki_backup --max-depth 5
- # Export APaaS database schema
- feishu-docx export-workspace-schema <workspace_id> -o ./database_schema.md
- # Export WeChat article to Markdown
- feishu-docx export-wechat "https://mp.weixin.qq.com/s/xxxxxx"
- # Export with PDF (requires the pdf extra)
- uv tool install 'feishu-docx[pdf]' # or: pip install 'feishu-docx[pdf]'
- feishu-docx export "https://xxx.feishu.cn/docx/xxx" --pdf
- # Export with company-branded PDF template
- feishu-docx export "https://xxx.feishu.cn/docx/xxx" --pdf --pdf-template ./brand.css
- # Export with logo on cover page
- feishu-docx export "https://xxx.feishu.cn/docx/xxx" --pdf --pdf-template ./brand.css --pdf-logo ./logo.svg
- # Export with syntax highlighting theme
- feishu-docx export "https://xxx.feishu.cn/docx/xxx" --pdf --syntax-style solarized-light
- # Fetch a WeChat article and create a Feishu doc
- feishu-docx create --url "https://mp.weixin.qq.com/s/xxxxxx"
- # List app cloud-space documents in tenant mode
- feishu-docx drive ls --type docx
- # Manage public permission of a document
- feishu-docx drive perm-show "https://xxx.feishu.cn/docx/xxx"
- feishu-docx drive perm-set "https://xxx.feishu.cn/docx/xxx" --share-entity anyone_can_view
- # Clear files in cloud space with double confirmation
- feishu-docx drive clear --type docx
- # Use token directly
- feishu-docx export "URL" -t your_access_token
- # Launch TUI
- feishu-docx tui
- ```
- ### Python API
- ```python
- from feishu_docx import FeishuExporter
- # Initialize (uses tenant_access_token by default)
- exporter = FeishuExporter(app_id="xxx", app_secret="xxx")
- # Export single document
- path = exporter.export("https://xxx.feishu.cn/wiki/xxx", "./output")
- # Get content without saving
- content = exporter.export_content("https://xxx.feishu.cn/docx/xxx")
- # Export with PDF (requires: uv tool install 'feishu-docx[pdf]' or pip install 'feishu-docx[pdf]')
- path = exporter.export("https://xxx.feishu.cn/docx/xxx", "./output", pdf=True)
- # Export with company-branded PDF template
- from pathlib import Path
- path = exporter.export(
- "https://xxx.feishu.cn/docx/xxx",
- "./output",
- pdf=True,
- pdf_template=Path("./brand.css"),
- pdf_logo=Path("./logo.svg"),
- syntax_style="solarized-light", # optional Pygments theme
- )
- # Export a public or browser-readable doc via a real browser session
- browser_path = exporter.export_with_browser(
- "https://xxx.larkoffice.com/wiki/xxx",
- "./browser_output",
- )
- # Get browser-based export content without saving
- browser_content = exporter.export_content_with_browser(
- "https://xxx.larkoffice.com/wiki/xxx",
- )
- # Batch export entire wiki space
- result = exporter.export_wiki_space(
- space_id="xxx",
- output_dir="./wiki_backup",
- max_depth=3,
- )
- print(f"Exported {result['exported']} docs to {result['space_dir']}")
- ```
- ---
- ## ๐ Feishu App Setup
- 1. Create app at [Feishu Open Platform](https://open.feishu.cn/)
- 2. Add redirect URL: `http://127.0.0.1:9527/`
- 3. Request permissions:
- ```python
- "docx:document:readonly" # ๆฅ็ไบๆๆกฃ
- "wiki:wiki:readonly" # ๆฅ็็ฅ่ฏๅบ
- "drive:drive:readonly" # ๆฅ็ไบ็ฉบ้ดๆไปถ๏ผๅพ็ไธ่ฝฝ๏ผ
- "sheets:spreadsheet:readonly" # ๆฅ็็ตๅญ่กจๆ ผ
- "bitable:app:readonly" # ๆฅ็ๅค็ปด่กจๆ ผ
- "board:whiteboard:node:read" # ๆฅ็็ฝๆฟ
- "contact:contact.base:readonly" # ่ทๅ็จๆทๅบๆฌไฟกๆฏ๏ผ@็จๆทๅ็งฐ๏ผ
- "offline_access" # ็ฆป็บฟ่ฎฟ้ฎ๏ผ่ทๅ refresh_token๏ผ
- ```
- 4. Save credentials:
- ```bash
- feishu-docx config set --app-id cli_xxx --app-secret xxx
- ```
- ### ๐ Authentication Modes
- | | **Tenant Mode** (Default) | **OAuth Mode** |
- |---|---|---|
- | **Token Type** | `tenant_access_token` | `user_access_token` |
- | **Setup** | Configure permissions in [Open Platform](https://open.feishu.cn/app) | Request permissions during OAuth flow |
- | **User Interaction** | โ Automatic, no user action needed | โ Requires browser authorization |
- | **Access Scope** | Documents the **app** has permission to | Documents the **user** has permission to |
- | **Best For** | Server automation, AI Agents | Accessing user's private documents |
- **Tenant Mode (Recommended for most cases):**
- ```bash
- # One-time setup
- feishu-docx config set --app-id xxx --app-secret xxx
- # Export (auto-obtains tenant_access_token)
- feishu-docx export "https://xxx.feishu.cn/docx/xxx"
- ```
- > โ ๏ธ Tenant mode requires pre-configuring document permissions in [Feishu Open Platform](https://open.feishu.cn/app) โ App Permissions.
- **Cloud space management (tenant/user):**
- ```bash
- # Tenant mode: manage files in app cloud space
- feishu-docx drive ls --type docx
- # OAuth mode: manage files in personal cloud space
- feishu-docx drive ls --auth-mode oauth --type docx
- ```
- > ๐ Feishu separates cloud space by token type: `tenant_access_token` maps to app cloud space, and `user_access_token` maps to personal cloud space. App cloud space resources cannot be managed from the UI and should be managed through Drive/File APIs.
- **OAuth Mode (For user-level access):**
- ```bash
- # One-time setup
- feishu-docx config set --app-id xxx --app-secret xxx --auth-mode oauth
- feishu-docx auth # Opens browser for authorization
- # Export (uses cached user_access_token)
- feishu-docx export "https://xxx.feishu.cn/docx/xxx"
- ```
- > ๐ก OAuth mode requests permissions during the authorization flow, no pre-configuration needed.
- ---
- ## ๐ Commands
- | Command | Description |
- |------------------------------------|-----------------------------------------|
- | `export <URL>` | Export single document to Markdown |
- | `export-browser <URL>` | Export a public or browser-readable doc in a real browser session |
- | `export-wiki-space <space_id>` | Batch export wiki space with hierarchy |
- | `export-workspace-schema <id>` | Export APaaS database schema |
- | `export-wechat <URL>` | Export WeChat article to Markdown |
- | `create <title>` | Create new Feishu document (`--url` supported) |
- | `drive ls` | List files in app/user cloud space |
- | `drive rm <TOKEN>` | Delete a file from cloud space |
- | `drive perm-show <TOKEN>` | Show public permission settings |
- | `drive perm-set <TOKEN>` | Update public permission settings |
- | `drive perm-members <TOKEN>` | List permission members |
- | `drive perm-add <TOKEN>` | Add a permission member |
- | `drive perm-update <TOKEN>` | Update a permission member |
- | `drive perm-rm <TOKEN>` | Remove a permission member |
- | `drive clear` | Clear files with double confirmation |
- | `write <URL>` | Append Markdown content to document |
- | `update <URL>` | Update specific block in document |
- | `auth` | OAuth authorization |
- | `tui` | Launch TUI interface |
- | `config set` | Set credentials |
- | `config show` | Show configuration |
- | `config clear` | Clear cache |
- ## ๐ Documentation Strategy
- - `README`: overview, quick start, and command index
- - `docs/*.md`: topic-focused guides for more complex workflows
- Currently available:
- - [Drive Management](./docs/drive-management.md)
- ---
- ## ๐บ๏ธ Roadmap
- - [x] Document/Sheet/Wiki export
- - [x] OAuth 2.0 + Token refresh
- - [x] TUI interface
- - [x] Claude Skills support
- - [x] Batch export entire wiki space
- - [x] Write to Feishu (create/update docs)
- - [x] Browser-based export with local assets
- ---
- ## ๐ Changelog
- See [CHANGELOG.md](./CHANGELOG.md) for version history.
- ## ๐ More Docs
- - [Drive Management](./docs/drive-management.md)
- ---
- ## ๐ License
- MIT License - See [LICENSE](LICENSE)
- ---
- **โญ Star this repo if you find it helpful!**
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If itโs helped, pass it on.