Skip to main content
Lab Grimoire
TW EN
☕ Coffee
Spellbook / beautiful-mermaid-cli ↗ Visit project
ai-tools

beautiful-mermaid-cli

A lightweight Mermaid diagram CLI renderer that requires no Puppeteer or Chromium. Uses a pure JS engine to render SVG, PNG, and ASCII output with 15 built-in themes and an AI agent JSON interface. Fully offline. Very new project supporting only 6 diagram types—watch status.

Best For

Developers who need to render Mermaid diagrams in CI environments or lightweight containers without carrying a 300MB Chromium dependency. Users who want ASCII diagram previews in the terminal. Privacy-conscious workflows requiring fully offline operation. Not suitable if you need Gantt, Mindmap, or Git Graph diagrams.

How I Actually Use It

As a complement to mmdc (the official mermaid-cli). I use bm ascii to quickly preview Flowcharts and Sequence Diagrams in the terminal, verify the structure is correct, then render final output with the full toolchain. The --json interface design (schema_version + semantic exit codes) also serves as a reference pattern for building my own CLI tools.

Where It Is Strong

  • No Puppeteer or Chromium needed, minimal install footprint
  • ASCII rendering is the standout feature—Unicode box-drawing characters display diagrams directly in the terminal
  • 15 built-in themes (tokyo-night, catppuccin, nord, dracula, and other Shiki-compatible themes)
  • --json flag outputs structured results with semantic exit codes (0 success / 1 WASM error / 2 usage / 3 parse / 4 I/O), making it easy to integrate with AI agents
  • Fully offline, zero network requests

Where It Fails

  • Only 6 diagram types supported (Flowchart / State / Sequence / Class / ER / XY Chart). Gantt, Mindmap, Git Graph, Pie, Timeline all unsupported.
  • Core dependency beautiful-mermaid uses latest with no version pinning; each install may pull a different version. Real supply chain risk.
  • Extremely new project—first release 2026-04-28, seven releases in 72 hours, API still in flux
  • CLI has only 23 Stars, single contributor, minimal community validation
  • PNG mode does not support Emoji (resvg-wasm limitation)

Pricing, Difficulty, and Risk

  • Completely free, MIT licensed
  • Very low difficulty: npm i -g beautiful-mermaid-cli or brew install okooo5km/tap/bm; requires Node.js >= 20
  • Risk: Unpinned core dependency is the primary concern; 7-day project history with unproven stability; third-party Homebrew tap maintained by a single author

Verdict

A well-designed lightweight Mermaid CLI with the right concept. ASCII rendering is the one thing no other tool does. But limited diagram type coverage, high supply chain risk, and extreme newness make it suitable only for experimental use today. Wait for beautiful-mermaid to support more types and reach semver 1.x stability before production adoption. Complementary to mmdc, not a replacement.

Source