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 and inject embed references. Three modes: inline (default, no quota, watermarked), share (Pro+, watermark-free), sidecar (local SVG files). Re-runs are idempotent.

IdempotentGitHub-renderablePro+ no-watermark

bd extract README.md                       # default: anonymous inline (watermarked)
bd extract README.md --share               # Pro+: /v1/share/<token>.svg (no watermark)
bd extract README.md --share --re-mint     # force fresh share tokens
bd extract docs/*.md --assets-dir ./img    # sidecar: local SVG files
bd extract README.md --dry-run             # preview without writing

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

Inject embed references for every Mermaid/PlantUML block in a Markdown file. Default inline (anonymous, watermarked); `--share` mints watermark-free per-source share URLs (Pro+); `--assets-dir` writes local SVG files.

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 injects ![]() references that actually display. Pick the mode based on whether you want a watermark, want local files, or want to keep things zero-quota.

# Default: anonymous inline URL — no API calls, no files, watermarked.
bd extract README.md
#   <!-- bd:inline-img hash=a3f9c2b1 -->
#   ![Diagram 1](https://api.beauty-diagram.com/v1/beautify.svg?source=...)
#   <!-- /bd:inline-img -->

# --share (Pro/Premium): mint /v1/share/<token>.svg per fence — no watermark.
# 1 share quota per unique source; identical fences are deduped; re-runs cached.
bd extract README.md --share
#   <!-- bd:inline-img hash=a3f9c2b1 share=true -->
#   ![Diagram 1](https://api.beauty-diagram.com/v1/share/Xs4PqM2NkL8t.svg)
#   <!-- /bd:inline-img -->

# --assets-dir: write local SVG files via /v1/export (Pro/Premium no-watermark).
bd extract README.md --assets-dir ./img
#   <!-- bd:img hash=a3f9c2b1 -->
#   ![Diagram 1](./img/readme-a3f9c2b1.svg)
#   <!-- /bd:img -->

Take ownership of share tokens after pulling a PR

When a teammate commits --share markers, the tokens belong to their account. Default bd extract --share preserves existing tokens to avoid noisy multi-PR rewrites. Use --re-mint when you want every fence reminted under your own API key (e.g. the original owner is leaving the project).

# Default: keep existing share tokens, only mint when the marker is
# missing or the source hash changed.
bd extract README.md --share

# --re-mint: force a fresh POST /v1/share for every fence, consuming
# 1 share quota per unique source under your account.
bd extract README.md --share --re-mint

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.

💡 You can embed theme and background overrides directly in your diagram source using %% bd:theme=... (Mermaid) or ' bd:theme=... (PlantUML) — no flag needed. See Source-level directives.

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 ↗