Skip to content
Back to search

feishu-docx

SkillWorks with Claude CodeGitHub

๐Ÿš€ 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.

Checked today

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
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/leemysw--feishu-docx/badge.svg)](/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

i

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)

  1. <div align="center">
  2. <img src="https://raw.githubusercontent.com/leemysw/feishu-docx/main/docs/icon.png" alt="feishu-docx" width="128">
  3. # feishu-docx
  4. <p align="center">
  5. <em>Feishu knowledge base export, writing, and cloud-space management tool with Markdown, WeChat import, CLI, TUI, and OAuth 2.0</em><br>
  6. </p>
  7. [![PyPI version](https://badge.fury.io/py/feishu-docx.svg)](https://badge.fury.io/py/feishu-docx)
  8. [![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
  9. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
  10. <p align="center">
  11. <a href="https://github.com/leemysw/feishu-docx/blob/main/README_zh.md">ไธญๆ–‡</a> | <strong>English</strong>
  12. </p>
  13. </div>
  14. <div align="center">
  15. <img src="https://raw.githubusercontent.com/leemysw/feishu-docx/main/docs/tui.png" alt="feishu-docx TUI" width="90%">
  16. </div>
  17. ---
  18. ## ๐Ÿ†• Recent Updates (v0.2.8)
  19. - 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))
  20. - Card-view links retain their titles and destinations; encoded URLs are preserved correctly
  21. - Refreshed project icon and added public-document Markdown/PDF end-to-end regression coverage
  22. Upgrade with `pip install --upgrade "feishu-docx[pdf]"` for PDF export, or `uv tool upgrade feishu-docx` for an existing uv tool installation.
  23. ---
  24. ## ๐ŸŽฏ Why feishu-docx?
  25. **Let AI Agents read, write, and manage your Feishu/Lark knowledge base.**
  26. - ๐Ÿค– **Built for AI** โ€” Works seamlessly with Claude/GPT Skills for document retrieval
  27. - ๐Ÿ“„ **Full Coverage** โ€” Documents, Spreadsheets, Bitables, Wiki nodes, and WeChat articles
  28. - โœ๏ธ **Write Back Support** โ€” Create docs, append content, and update specific blocks
  29. - โ˜๏ธ **Cloud-Space Management** โ€” List files, delete files, manage permissions, clear files safely
  30. - ๐Ÿ” **Authentication** โ€” One-time auth, automatic token refresh
  31. - ๐ŸŽจ **Dual Interface** โ€” CLI + Beautiful TUI (Textual-based)
  32. - ๐Ÿ“ฆ **Easy Install** โ€” `uv tool install feishu-docx` or `pip install feishu-docx`
  33. ---
  34. ## โšก Quick Start (30 seconds)
  35. ### Install
  36. **Recommended: `uv tool install`** (isolated, no conflicts with system Python)
  37. ```bash
  38. uv tool install feishu-docx
  39. ```
  40. Optional features are installed separately to keep the core package lightweight:
  41. ```bash
  42. # PDF export: --pdf, --pdf-template, --pdf-logo, syntax highlighting
  43. uv tool install 'feishu-docx[pdf]'
  44. # Browser-based export: export-browser
  45. uv tool install 'feishu-docx[browser]'
  46. playwright install chromium
  47. ```
  48. Or run directly without installing:
  49. ```bash
  50. uvx feishu-docx export "https://my.feishu.cn/wiki/xxx"
  51. ```
  52. If you don't have `uv` yet: `curl -LsSf https://astral.sh/uv/install.sh | sh`
  53. **Alternative: `pip install`** (works inside a virtual environment or with `--break-system-packages`)
  54. ```bash
  55. pip install feishu-docx
  56. ```
  57. Optional extras also work with `pip`:
  58. ```bash
  59. pip install 'feishu-docx[pdf]'
  60. pip install 'feishu-docx[browser]'
  61. playwright install chromium
  62. ```
  63. > Quote extras such as `'feishu-docx[pdf]'` in shells like zsh, otherwise the `[]` may be treated as a glob pattern.
  64. > โš ๏ธ `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.
  65. ### Configure and Export
  66. ```bash
  67. # Configure credentials (one-time)
  68. feishu-docx config set --app-id YOUR_APP_ID --app-secret YOUR_APP_SECRET
  69. # Export! (auto-obtains tenant_access_token, no OAuth needed)
  70. feishu-docx export "https://my.feishu.cn/wiki/KUIJwaBuGiwaSIkkKJ6cfVY8nSg"
  71. # Create a Feishu doc directly from a WeChat article
  72. feishu-docx create --url "https://mp.weixin.qq.com/s/xxxxx"
  73. # Manage app cloud-space documents
  74. feishu-docx drive ls --type docx
  75. # Optional: Use OAuth mode for user-level permissions
  76. # feishu-docx config set --auth-mode oauth && feishu-docx auth
  77. ```
  78. ---
  79. ## ๐Ÿค– Skills Support
  80. **Enable Agent to access your Feishu knowledge base directly!**
  81. This project includes a Claude Skill at `.skills/feishu-docx/SKILL.md`.
  82. Supports OpenCode, Claude Code, Codex, Cursor, and more.
  83. Copy this Skill to your agent project, and Claude can:
  84. - ๐Ÿ“– Read Feishu knowledge base as context
  85. - ๐Ÿ” Search and reference internal documents
  86. - ๐Ÿ“ Create docs, append content, and update specific blocks
  87. ---
  88. ## โœจ Features
  89. | Feature | Description |
  90. |-------------------------|-------------------------------------------------|
  91. | ๐Ÿ“„ Document Export | Docx โ†’ Markdown with formatting, images, tables |
  92. | ๐Ÿ“Š Spreadsheet Export | Sheet โ†’ Markdown tables, with rich-text cells and display/formula modes |
  93. | ๐Ÿ“‹ Bitable Export | Multidimensional tables โ†’ Markdown |
  94. | ๐Ÿ“š Wiki Export | Auto-resolve wiki nodes |
  95. | ๐Ÿ—‚๏ธ Wiki Batch Export | Recursively export entire wiki space with hierarchy |
  96. | โœ๏ธ Document Writing | Create docs, append Markdown, update specific blocks |
  97. | ๐Ÿ“ฐ WeChat Import/Export | Export WeChat articles or create Feishu docs from them |
  98. | ๐ŸŒ Browser-Based Export | Export public docs or docs accessible in the current browser session, with local assets |
  99. | โ˜๏ธ Drive Management | List files, delete files, manage permissions, clear files |
  100. | ๐Ÿ—„๏ธ Database Schema | Export APaaS database structure to Markdown |
  101. | ๐Ÿงท Local Asset Download | Images and attachments saved locally with relative paths |
  102. | ๐Ÿ–จ๏ธ PDF Export | Generate branded PDF with WeasyPrint, custom CSS templates |
  103. | ๐Ÿ” Auth | Auto tenant_access_token (recommended) or OAuth 2.0 |
  104. | ๐ŸŽจ Beautiful TUI | Terminal UI powered by Textual |
  105. ### โœ… Supported Blocks
  106. This tool currently supports exporting the following Feishu/Lark document components:
  107. | Category | Features | Status | Notes |
  108. |----------------|----------------------------------------------------------------|--------|------------------------------------------|
  109. | **Basic Text** | Headings, Paragraphs, Lists, Tasks (Todo), Code Blocks, Quotes | โœ… | Fully Supported |
  110. | **Formatting** | Bold, Italic, Strikethrough, Underline, Links, @Mentions | โœ… | Fully Supported |
  111. | **Layout** | Columns, Callouts, Dividers | โœ… | Fully Supported |
  112. | **Tables** | Native Tables | โœ… | Export to Markdown/HTML |
  113. | **Media** | Images, Drawing Boards | โœ… | Drawing boards exported as images |
  114. | **Embedded** | Spreadsheets (Sheets), Bitable | โœ… | Sheets support rich-text cells and display/formula modes |
  115. | **Special** | Synced Blocks, Add-ons Blocks | โœ… | Synced blocks support same-document and cross-document references |
  116. | **Files** | Attachments | โœ… | Local download when possible, temp link fallback |
  117. ---
  118. ## ๐Ÿ“– Usage
  119. ### Use Cases
  120. - Export Feishu docs, Sheets, Bitables, and Wiki nodes to Markdown
  121. - Export a WeChat article to Markdown
  122. - Create a Feishu doc directly from a WeChat article URL
  123. - Create, append, or update Feishu document content
  124. - Manage files and permissions in app cloud space or personal cloud space
  125. ### CLI
  126. `export-browser` requires Playwright.
  127. If you installed via `uv tool install`, install the browser extra:
  128. ```bash
  129. uv tool install 'feishu-docx[browser]'
  130. playwright install chromium
  131. ```
  132. If you are working inside a virtual environment:
  133. ```bash
  134. pip install 'feishu-docx[browser]'
  135. playwright install chromium
  136. ```
  137. ```bash
  138. # Export single document to specific directory
  139. feishu-docx export "https://xxx.feishu.cn/docx/xxx" -o ./docs
  140. # Choose display values or formulas for Sheets (affects Sheet and embedded Sheet only)
  141. feishu-docx export "https://xxx.feishu.cn/wiki/xxx" --table md --sheet-value-mode display
  142. feishu-docx export "https://xxx.feishu.cn/wiki/xxx" --table md --sheet-value-mode formula
  143. # Export a public or browser-readable doc in a real browser session
  144. feishu-docx export-browser "https://xxx.larkoffice.com/wiki/xxx" -o ./browser_docs
  145. # Export with existing Playwright storage state
  146. feishu-docx export-browser "https://xxx.larkoffice.com/wiki/xxx" --storage-state ./storage_state.json
  147. # Batch export entire wiki space (preserves hierarchy)
  148. feishu-docx export-wiki-space <space_id_or_url> -o ./wiki_backup --max-depth 5
  149. # Export APaaS database schema
  150. feishu-docx export-workspace-schema <workspace_id> -o ./database_schema.md
  151. # Export WeChat article to Markdown
  152. feishu-docx export-wechat "https://mp.weixin.qq.com/s/xxxxxx"
  153. # Export with PDF (requires the pdf extra)
  154. uv tool install 'feishu-docx[pdf]' # or: pip install 'feishu-docx[pdf]'
  155. feishu-docx export "https://xxx.feishu.cn/docx/xxx" --pdf
  156. # Export with company-branded PDF template
  157. feishu-docx export "https://xxx.feishu.cn/docx/xxx" --pdf --pdf-template ./brand.css
  158. # Export with logo on cover page
  159. feishu-docx export "https://xxx.feishu.cn/docx/xxx" --pdf --pdf-template ./brand.css --pdf-logo ./logo.svg
  160. # Export with syntax highlighting theme
  161. feishu-docx export "https://xxx.feishu.cn/docx/xxx" --pdf --syntax-style solarized-light
  162. # Fetch a WeChat article and create a Feishu doc
  163. feishu-docx create --url "https://mp.weixin.qq.com/s/xxxxxx"
  164. # List app cloud-space documents in tenant mode
  165. feishu-docx drive ls --type docx
  166. # Manage public permission of a document
  167. feishu-docx drive perm-show "https://xxx.feishu.cn/docx/xxx"
  168. feishu-docx drive perm-set "https://xxx.feishu.cn/docx/xxx" --share-entity anyone_can_view
  169. # Clear files in cloud space with double confirmation
  170. feishu-docx drive clear --type docx
  171. # Use token directly
  172. feishu-docx export "URL" -t your_access_token
  173. # Launch TUI
  174. feishu-docx tui
  175. ```
  176. ### Python API
  177. ```python
  178. from feishu_docx import FeishuExporter
  179. # Initialize (uses tenant_access_token by default)
  180. exporter = FeishuExporter(app_id="xxx", app_secret="xxx")
  181. # Export single document
  182. path = exporter.export("https://xxx.feishu.cn/wiki/xxx", "./output")
  183. # Get content without saving
  184. content = exporter.export_content("https://xxx.feishu.cn/docx/xxx")
  185. # Export with PDF (requires: uv tool install 'feishu-docx[pdf]' or pip install 'feishu-docx[pdf]')
  186. path = exporter.export("https://xxx.feishu.cn/docx/xxx", "./output", pdf=True)
  187. # Export with company-branded PDF template
  188. from pathlib import Path
  189. path = exporter.export(
  190. "https://xxx.feishu.cn/docx/xxx",
  191. "./output",
  192. pdf=True,
  193. pdf_template=Path("./brand.css"),
  194. pdf_logo=Path("./logo.svg"),
  195. syntax_style="solarized-light", # optional Pygments theme
  196. )
  197. # Export a public or browser-readable doc via a real browser session
  198. browser_path = exporter.export_with_browser(
  199. "https://xxx.larkoffice.com/wiki/xxx",
  200. "./browser_output",
  201. )
  202. # Get browser-based export content without saving
  203. browser_content = exporter.export_content_with_browser(
  204. "https://xxx.larkoffice.com/wiki/xxx",
  205. )
  206. # Batch export entire wiki space
  207. result = exporter.export_wiki_space(
  208. space_id="xxx",
  209. output_dir="./wiki_backup",
  210. max_depth=3,
  211. )
  212. print(f"Exported {result['exported']} docs to {result['space_dir']}")
  213. ```
  214. ---
  215. ## ๐Ÿ” Feishu App Setup
  216. 1. Create app at [Feishu Open Platform](https://open.feishu.cn/)
  217. 2. Add redirect URL: `http://127.0.0.1:9527/`
  218. 3. Request permissions:
  219. ```python
  220. "docx:document:readonly" # ๆŸฅ็œ‹ไบ‘ๆ–‡ๆกฃ
  221. "wiki:wiki:readonly" # ๆŸฅ็œ‹็Ÿฅ่ฏ†ๅบ“
  222. "drive:drive:readonly" # ๆŸฅ็œ‹ไบ‘็ฉบ้—ดๆ–‡ไปถ๏ผˆๅ›พ็‰‡ไธ‹่ฝฝ๏ผ‰
  223. "sheets:spreadsheet:readonly" # ๆŸฅ็œ‹็”ตๅญ่กจๆ ผ
  224. "bitable:app:readonly" # ๆŸฅ็œ‹ๅคš็ปด่กจๆ ผ
  225. "board:whiteboard:node:read" # ๆŸฅ็œ‹็™ฝๆฟ
  226. "contact:contact.base:readonly" # ่Žทๅ–็”จๆˆทๅŸบๆœฌไฟกๆฏ๏ผˆ@็”จๆˆทๅ็งฐ๏ผ‰
  227. "offline_access" # ็ฆป็บฟ่ฎฟ้—ฎ๏ผˆ่Žทๅ– refresh_token๏ผ‰
  228. ```
  229. 4. Save credentials:
  230. ```bash
  231. feishu-docx config set --app-id cli_xxx --app-secret xxx
  232. ```
  233. ### ๐Ÿ”‘ Authentication Modes
  234. | | **Tenant Mode** (Default) | **OAuth Mode** |
  235. |---|---|---|
  236. | **Token Type** | `tenant_access_token` | `user_access_token` |
  237. | **Setup** | Configure permissions in [Open Platform](https://open.feishu.cn/app) | Request permissions during OAuth flow |
  238. | **User Interaction** | โœ… Automatic, no user action needed | โŒ Requires browser authorization |
  239. | **Access Scope** | Documents the **app** has permission to | Documents the **user** has permission to |
  240. | **Best For** | Server automation, AI Agents | Accessing user's private documents |
  241. **Tenant Mode (Recommended for most cases):**
  242. ```bash
  243. # One-time setup
  244. feishu-docx config set --app-id xxx --app-secret xxx
  245. # Export (auto-obtains tenant_access_token)
  246. feishu-docx export "https://xxx.feishu.cn/docx/xxx"
  247. ```
  248. > โš ๏ธ Tenant mode requires pre-configuring document permissions in [Feishu Open Platform](https://open.feishu.cn/app) โ†’ App Permissions.
  249. **Cloud space management (tenant/user):**
  250. ```bash
  251. # Tenant mode: manage files in app cloud space
  252. feishu-docx drive ls --type docx
  253. # OAuth mode: manage files in personal cloud space
  254. feishu-docx drive ls --auth-mode oauth --type docx
  255. ```
  256. > ๐Ÿ“Ž 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.
  257. **OAuth Mode (For user-level access):**
  258. ```bash
  259. # One-time setup
  260. feishu-docx config set --app-id xxx --app-secret xxx --auth-mode oauth
  261. feishu-docx auth # Opens browser for authorization
  262. # Export (uses cached user_access_token)
  263. feishu-docx export "https://xxx.feishu.cn/docx/xxx"
  264. ```
  265. > ๐Ÿ’ก OAuth mode requests permissions during the authorization flow, no pre-configuration needed.
  266. ---
  267. ## ๐Ÿ“– Commands
  268. | Command | Description |
  269. |------------------------------------|-----------------------------------------|
  270. | `export <URL>` | Export single document to Markdown |
  271. | `export-browser <URL>` | Export a public or browser-readable doc in a real browser session |
  272. | `export-wiki-space <space_id>` | Batch export wiki space with hierarchy |
  273. | `export-workspace-schema <id>` | Export APaaS database schema |
  274. | `export-wechat <URL>` | Export WeChat article to Markdown |
  275. | `create <title>` | Create new Feishu document (`--url` supported) |
  276. | `drive ls` | List files in app/user cloud space |
  277. | `drive rm <TOKEN>` | Delete a file from cloud space |
  278. | `drive perm-show <TOKEN>` | Show public permission settings |
  279. | `drive perm-set <TOKEN>` | Update public permission settings |
  280. | `drive perm-members <TOKEN>` | List permission members |
  281. | `drive perm-add <TOKEN>` | Add a permission member |
  282. | `drive perm-update <TOKEN>` | Update a permission member |
  283. | `drive perm-rm <TOKEN>` | Remove a permission member |
  284. | `drive clear` | Clear files with double confirmation |
  285. | `write <URL>` | Append Markdown content to document |
  286. | `update <URL>` | Update specific block in document |
  287. | `auth` | OAuth authorization |
  288. | `tui` | Launch TUI interface |
  289. | `config set` | Set credentials |
  290. | `config show` | Show configuration |
  291. | `config clear` | Clear cache |
  292. ## ๐Ÿ“š Documentation Strategy
  293. - `README`: overview, quick start, and command index
  294. - `docs/*.md`: topic-focused guides for more complex workflows
  295. Currently available:
  296. - [Drive Management](./docs/drive-management.md)
  297. ---
  298. ## ๐Ÿ—บ๏ธ Roadmap
  299. - [x] Document/Sheet/Wiki export
  300. - [x] OAuth 2.0 + Token refresh
  301. - [x] TUI interface
  302. - [x] Claude Skills support
  303. - [x] Batch export entire wiki space
  304. - [x] Write to Feishu (create/update docs)
  305. - [x] Browser-based export with local assets
  306. ---
  307. ## ๐Ÿ“œ Changelog
  308. See [CHANGELOG.md](./CHANGELOG.md) for version history.
  309. ## ๐Ÿ“š More Docs
  310. - [Drive Management](./docs/drive-management.md)
  311. ---
  312. ## ๐Ÿ“„ License
  313. MIT License - See [LICENSE](LICENSE)
  314. ---
  315. **โญ Star this repo if you find it helpful!**

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If itโ€™s helped, pass it on.