# feishu-cli Review: Markdown, Feishu Documents, and Agent Automation

> feishu-cli is a Go command-line interface for Feishu documents, spreadsheets, messages, calendars, tasks, and related APIs. Its main differentiator is bidirectional Markdown conversion with editable diagram support, while its 503-command surface and Agent skills create a wide operational scope.

**riba2534/feishu-cli** — feishu-cli 是一个功能完整的飞书开放平台命令行工具。它将飞书文档、知识库、电子表格、消息、日历、任务等操作封装为简洁的命令行接口，核心能力是 Markdown ↔ 飞书文档双向无损转换。

- Repository: https://github.com/riba2534/feishu-cli
- Stars: 1,438 · Forks: 145
- Language: Go
- License: MIT
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/riba2534-feishu-cli

## What feishu-cli Covers and Who It Targets

feishu-cli packages Feishu Open Platform operations into a command-line interface. The documented scope extends beyond documents to knowledge bases, spreadsheets, bitables, messages, chats, email, calendars, tasks, meetings, minutes, approvals, attendance, OKRs, cloud drives, permissions, whiteboards, Slides, events, schemas, profiles, and health checks. The README says the project primarily targets AI Agents such as Claude Code, while also allowing people to invoke the CLI directly.

The central use case is moving technical content between local Markdown and Feishu documents. An import creates a Feishu document from a local file, and an export retrieves a document as Markdown, with optional image downloading. The project documentation also describes support for 40 or more block types, nested lists, task lists, code blocks, quotes, callouts, synchronized blocks, tables, dividers, images, links, formulas, and common inline formatting. That makes it useful for engineers who want document changes to be scripted, reviewed in Git, or initiated by an Agent.

The breadth is also a caution. A single binary exposes 503 commands across many API areas. This can be useful for automation, but it increases the number of permission, object, and output details that a team must understand before allowing writes. The README does not describe a separate minimal profile for read-only or document-only use.

## How feishu-cli Converts and Processes Documents

The import path is not a simple upload of raw Markdown. The project parses document structure and creates Feishu blocks in document order. During this first stage, it collects work for diagrams and tables. A second stage uses separate worker pools for diagrams and tables, while the README also documents image workers. A third stage processes failed diagrams in reverse order and can downgrade them to code blocks.

This architecture addresses a specific problem in the Feishu document API. The README states that document creation has a nine-row limit for each `create_block` request, so large tables are created with an initial table and extended through `insert_table_row`. Cell filling uses `batch_update`, with batches of up to 30 cells, and document processing includes a 3 QPS throttle.

Markdown diagrams receive special treatment. Mermaid and PlantUML fenced blocks are converted into Feishu whiteboards rather than raster screenshots. The documented Mermaid set includes flowcharts, sequence diagrams, class diagrams, state diagrams, ER diagrams, Gantt diagrams, pie charts, and mind maps. State diagrams must use `stateDiagram-v2`. If a diagram cannot be converted, the README says the original text is retained as a code block instead of allowing the full import to stop.

Export does not claim perfect equivalence for every edge case. The README specifically notes that unreadable cross-document synchronized blocks are represented by a warning placeholder with source identification and diagnostics. It also says `<mark>` highlighting is currently approximated with an underline. Those are concrete boundaries for a round-trip workflow.

## feishu-cli Installation and First Document Import

The README presents an installation script that identifies the platform and performs a sha256 integrity check. The first real workflow is to create the Feishu application, save its credentials, and import a local Markdown file. The documented commands are:

```bash
curl -fsSL https://raw.githubusercontent.com/riba2534/feishu-cli/main/install.sh | bash
```

After installation, the README uses the following command to create an application through a Device Flow workflow and save the credentials:

```bash
feishu-cli config create-app --save
```

A first document import can then be issued against an existing Markdown file:

```bash
feishu-cli doc import README.md --title "我的第一篇文档"
```

The README says user identity authorization is only needed for capabilities that require a user, including search, approvals, and email. In that case it documents `feishu-cli auth login` for OAuth authorization. The project is written in Go and declares Go 1.21 in `go.mod`, while the README badge states Go 1.21 or later.

For a developer building from the repository, the Makefile provides a separate `make build` target and an `install` target that writes the binary to `$GOPATH/bin`. Those targets are repository build commands, not an additional user authentication path. The documentation does not explain how to map Feishu scopes to every command, so the first import should be performed with a minimally understood application permission set.

## CLI Controls for Scripts, Agents, and Large Imports

feishu-cli is designed to be consumed by both shell scripts and AI Agents. The README describes unified `--jq` and `--format` options for structured output, typo suggestions for misspelled commands or flags, `--dry-run` for write operations, and idempotency keys that help prevent duplicate messages. These features matter when a command is generated by an Agent rather than typed interactively.

The project also includes nine domain Skill files, and the README states that all 503 commands are covered by the skills. Claude Code is named as an example integration, but the repository layout includes a `skills/` directory and `skills_embed.go`, indicating that the skills are part of the distributed Go project rather than an unrelated external add-on. The documented Agent use case includes creating documents, sending messages, and managing permissions.

Large-document imports can tune worker counts. The README gives this example:

```bash
feishu-cli doc import large-doc.md --title "大文档" \
  --upload-images --diagram-workers 5 --table-workers 3 --image-workers 2 --verbose
```

The flags expose the documented three-stage pipeline directly. They do not guarantee that every external asset will be accepted by Feishu. Image upload, diagram conversion, API throttling, and permission checks remain separate failure points. For an Agent, the safer operating pattern is to use dry-run output first, inspect the generated document identifier and diagnostics, and only then permit write operations.

The repository also includes offline contract checks in the Makefile. `make check-skill-contracts` builds the current source and runs offline CLI contracts without a live Feishu API. `make check-skills` additionally checks Skill YAML, examples, ownership, and offline behavior. These targets are relevant to teams modifying the binary, but they do not validate live tenant permissions.

## Where feishu-cli Falls Short

The first limitation is conversion fidelity. The README calls the feature lossless, but it also identifies exceptions. Cross-document synchronized blocks may be unreadable, in which case export leaves a warning placeholder rather than reproducing the remote content. Highlight syntax is approximated. Diagram conversion has supported types and syntax constraints, and a failed diagram is downgraded to a code block. Therefore, the tool is strong for ordinary technical Markdown, but a team should not treat every Feishu document as a perfectly lossless Markdown file.

The second limitation is operational scope. Commands for email, approvals, calendars, meetings, permissions, and messages may require different token types and application scopes. The README identifies Bot and User identities in several areas, and it specifically says mail capabilities need a User Token. It does not provide a complete permission matrix in the visible quick-start instructions. An automation that appears correct locally can fail because the Feishu application lacks a scope, because the object is owned by another tenant, or because user authorization has expired.

The third limitation is fallback behavior. Preserving a failed diagram as source code is preferable to losing it, but it changes the resulting Feishu representation. Similarly, a wide API surface gives a caller many ways to modify shared business objects. Dry-run and idempotency reduce some write risk, but the README does not claim transactional rollback across a multi-command Agent workflow. A failure after a document is created and before a message is sent should not be assumed to undo either action.

## feishu-cli Compared with Direct Feishu API Scripts

A direct Feishu Open Platform script uses the underlying API client and gives the caller explicit control over request construction, authentication, object selection, and error handling. That approach is appropriate when an application already has an SDK abstraction, needs an API surface that feishu-cli does not expose, or requires a custom transactional design.

feishu-cli takes a different approach. It supplies a broad command vocabulary, structured output filters, document conversion, worker-based import processing, built-in diagram conversion, dry-run controls, idempotency support, and Agent skills. A script that implements Markdown import manually would need to handle block creation, table growth, diagram conversion, asset upload, rate limiting, diagnostics, and output parsing itself. The CLI is therefore more convenient when its documented abstractions match the document shape you use.

The trade-off is abstraction. Direct API code exposes more of the protocol and can be adapted precisely, while feishu-cli hides some of that behavior behind commands and defaults. Its own dependency set includes `github.com/larksuite/oapi-sdk-go/v3`, `cobra`, `viper`, `goldmark`, and `gojq`, which reflects a Go application that combines SDK access, CLI parsing, configuration, Markdown parsing, and JSON filtering. A direct SDK script may be easier to reason about for a narrow integration; feishu-cli is more productive for document automation across several Feishu modules.

## Maintenance, License, and Upgrade Considerations

The repository is not archived, and the last push was on 2026-10-09. Recent releases include v1.43.0 on 2026-10-09, v1.42.0 on 2026-10-09, and v1.41.0 on 2026-09-22. This indicates recent release activity, although the README and repository files do not promise a particular support window or compatibility policy for Feishu API changes.

The repository identifies the project under the MIT license and includes `LICENSE` and `THIRD_PARTY_NOTICES.md`. The Go module requires Go 1.21 and pins several direct dependencies. An upgrade can therefore affect the Go toolchain, API client behavior, Markdown parser behavior, and command output at the same time. The Makefile includes `test`, `check-privacy`, and skill-related checks, which are useful project-specific verification points when changing a local build.

The visible README does not document a rollback procedure for a release, nor does it provide a formal compatibility matrix for Feishu scopes. Users should treat upgrades as changes to both the CLI and the remote integration surface. The documented `config create-app --save` flow should also be treated as credential-management work, with local credential storage and secret exposure reviewed according to the deployment's own policy.

## Conclusion

Adopt feishu-cli when you need repeatable Feishu operations from scripts or an AI coding assistant, especially when local Markdown and editable diagrams are central to the workflow. Do not choose it as a general-purpose Feishu SDK or assume every document construct is fully identical after a round trip. Verify authentication scopes, application permissions, diagram conversion results, and the behavior of your specific document structures before automating production changes.

## FAQ

### How do I install feishu-cli and import my first Markdown document into Feishu?

The README documents installing it with `curl -fsSL https://raw.githubusercontent.com/riba2534/feishu-cli/main/install.sh | bash`. Then use `feishu-cli config create-app --save` and run `feishu-cli doc import README.md --title "我的第一篇文档"`.

### Does feishu-cli convert Mermaid and PlantUML into editable Feishu content?

Yes. The README states that Mermaid and PlantUML fenced blocks are converted into Feishu whiteboards rather than screenshots. Mermaid support is documented for eight diagram categories, and PlantUML supports its listed diagram types.

### What are the limitations of Markdown import and export in feishu-cli?

The README says unreadable cross-document synchronized blocks become warning placeholders, and `<mark>` highlighting is approximated with an underline. Failed diagrams can be retained as code blocks instead of native whiteboards, so a round trip should not be assumed to preserve every Feishu-specific construct.

### Does feishu-cli support AI Agent integration with Claude Code?

The README names Claude Code as an example and describes nine domain skills that let an Agent call Feishu operations. It also documents structured output, dry-run write controls, idempotency keys, and skill coverage for the project's commands.

## Sources

- [Issues](https://github.com/riba2534/feishu-cli/issues)
- [License: MIT](https://github.com/riba2534/feishu-cli/blob/main/LICENSE)
- [README](https://github.com/riba2534/feishu-cli/blob/main/README.md)
- [Releases](https://github.com/riba2534/feishu-cli/releases)
- [riba2534/feishu-cli on GitHub](https://github.com/riba2534/feishu-cli)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/riba2534-feishu-cli