Tooling · npm

The bd CLI

Render, share, and embed Mermaid / PlantUML diagrams straight from the terminal. Same engine and quotas as the API, zero runtime dependencies, first-class workflows for repos and CI.

See workflows View on npm ↗API reference

bash · ~/your-repo

# zero-install via npx
$ npx @beauty-diagram/cli beautify flow.mmd --out flow.svg

# global install
$ npm install -g @beauty-diagram/cli
$ bd batch ./diagrams --out-dir ./svg

# → bd batch: 12 file(s), concurrency=4
  ✓ svg (flowchart). 7/100 → ./svg/release.svg
  ✓ svg (sequence). 8/100 → ./svg/auth.svg
  …

01

Parallel by default

Concurrency cap, fail-soft.

02

Idempotent re-runs

Markdown extract uses content hashes.

03

Zero runtime deps

Sub-second cold start under npx.

04

Same auth & quotas

One API key works for the editor, API, and CLI.

Three workflows

From one diagram to a whole repo

Each workflow uses the same auth and the same backend — pick the shape that matches the task. The newer batch and Markdown commands are pure client-side orchestration on top of POST /v1/export, so quotas behave the same as a single render.

Single diagram

Beautify, export to SVG/PNG, or create a public share link for one diagram source file.

Mermaid + PlantUMLSVG / PNG

bd beautify flow.mmd --theme modern --out flow.svg
bd export   flow.mmd --format png --scale 2 --out flow.png
bd share    flow.mmd --title "Release flow"

Batch render

New

Render every diagram under a directory in parallel — one /v1/export request per file. Failures are reported per-file; the rest of the batch keeps going.

ParallelRecursive .mmd / .puml

bd batch ./diagrams --out-dir ./svg
bd batch "docs/*.mmd" --format png --concurrency 8
bd batch ./d --stop-on-error              # abort on first failure

Embed in Markdown

New

Find every ```mermaid / ```plantuml fenced block in a Markdown file, render to sidecar SVGs, and inject ![](path) references right below the fence. Re-runs are idempotent.

IdempotentGitHub-renderable

bd extract README.md
bd extract docs/*.md --assets-dir ./img --concurrency 4
bd extract README.md --dry-run            # preview without writing
bd extract README.md --clean              # remove orphaned SVGs

Reference

All commands

bd themes

List available themes.

bd beautify

Render a diagram source to a polished SVG.

bd export

Export SVG or PNG with scale control. Counts toward export quota.

bd batchNew

Parallel-render many sources at once.

bd extractNew

Render Mermaid blocks inside Markdown to sidecar SVGs.

bd share

Create a public share link for a diagram.

bd embed-url <file>New

Print the embed URL(s) for a diagram source. Default outputs an anonymous (watermarked) inline URL plus a hint; --share saves the diagram first and prints a clean share embed URL.

bd ai generate

Generate Mermaid source from a text prompt (paid plan).

bd usage

Print current plan + remaining quota.

bd auth login

Save an API key to your OS config dir.

bd help

Show all commands and global flags.

Run bd help for the full flag list, or pass --help to any subcommand.

Recipes

Real-world patterns

Auto-render diagrams in CI

Commit Mermaid sources, regenerate the SVGs on every push. Diff-friendly output, no hand-edited binaries.

# .github/workflows/diagrams.yml step
- run: npx -y @beauty-diagram/cli batch ./diagrams --out-dir ./diagrams/svg
  env:
    BEAUTY_DIAGRAM_API_KEY: ${{ secrets.BEAUTY_DIAGRAM_API_KEY }}

Make GitHub render Mermaid as polished SVGs

GitHub strips inline <svg>; bd extract writes sidecar files and injects ![]() references that actually display.

bd extract README.md
# README.md is now self-rendering on github.com:
#   <!-- bd:img hash=a3f9c2b1 -->
#   ![Diagram 1](./assets/readme-a3f9c2b1.svg)
#   <!-- /bd:img -->

Embed a diagram as an `<img>` URL

bd embed-url prints the embed URL without saving. Use --share to save the diagram first and get a clean, watermark-free URL (Pro / Premium; requires bd auth login).

# Quick GitHub README embed (anonymous, watermarked)
bd embed-url ./architecture.mmd --theme atlas

# Pro/Premium clean embed (requires bd auth login first)
bd embed-url ./architecture.mmd --share

Prompt → diagram in one pipe

Generate Mermaid via AI and pipe it directly into beautify — no temp file. Save the source too if you might iterate.

bd ai generate "user signup with email verification" \
  | bd beautify - --theme modern --out signup.svg

Audit a docs site for stale diagrams

--dry-run previews every change bd extract would make without touching disk — pair with --clean later to delete orphaned SVGs from old hashes.

bd extract docs/**/*.md --dry-run
bd extract docs/**/*.md --clean

Auth & config

One key, three modes

The CLI reads keys in this order: --api-key flag, BEAUTY_DIAGRAM_API_KEY env, saved config from bd auth login, then anonymous demo. The --base-url flag follows the same precedence — useful for self-hosted runs.

Anonymous

Watermarked SVG, IP-rate-limited. Great for the first npx run.

Env var (CI)

Set BEAUTY_DIAGRAM_API_KEY in the runner. The CLI never logs the key.

Saved config

bd auth login stores the key in your OS config dir for everyday use.

💡 Errors, quotas, and rate limits are documented in the API reference. The CLI surfaces the same error envelope verbatim.

Install once, render anywhere

The free plan covers 3 watermark-free exports a month — enough to wire up CI and feel out the workflow before you commit to anything.

Create API key npm package ↗