pele-cli

Render Mermaid diagrams to SVG or PNG from the command line. This is a thin wrapper around Pele, the fast zero-dependency Mermaid renderer from the Obsidian team. PNG output is rasterized with resvg.

The source is TypeScript. Build and type checking use Bun (bun check, bun build --no-bundle), which transpile src/ to plain ESM in dist/ with no bundling. Development requires Bun; consumers need only Node.js 20+ or Bun. Node.js and Bun are both verified in tests.

Install

Published on npm as @simhozebs/pele-cli (the unscoped name is intentionally unclaimed).

npm install -g @simhozebs/pele-cli

Or run it without installing:

npx @simhozebs/pele-cli diagram.mmd -o diagram.svg   # Node
bunx @simhozebs/pele-cli diagram.mmd -o diagram.svg  # Bun

The command installed is pele. Pele supports Node.js 20 or later.

Usage

pele diagram.mmd              # render a file to stdout
pele diagram.mmd -o out.svg   # write the SVG to a file
pele diagram.mmd -o out.png   # write a PNG to a file
cat diagram.mmd | pele        # read from stdin
pele - < diagram.mmd          # explicit stdin

Options

| Option | Description | | --- | --- | | -o, --output <file> | Write output to <file> (- means stdout). A .png extension selects PNG. | | --format <svg\|png> | Force the output format. Default: inferred from -o, or SVG for stdout. | | --scale <n> | PNG scale factor (default 1). Errors unless the output format is PNG. | | --max-width <px> | Maximum width in pixels (responsive layout) | | --font-size <px> | Base font size in pixels (default 16) | | --font-family <f> | Label font family (default sans-serif) | | --padding <px> | Space around the diagram in pixels | | --id-prefix <s> | Prefix for SVG IDs (letters, digits, -, _) | | --no-responsive | Fixed pixel size instead of shrink-to-fit | | --no-auto-direction | Keep the source direction on narrow widths | | -h, --help | Show help | | -v, --version | Show version |

PNG output has a transparent background by default.

Exit codes

| Code | Meaning | | --- | --- | | 0 | Success | | 1 | Render error. The PeleError code and message print to stderr, with the source snippet when available. | | 2 | Usage or I/O error. |

Examples

$ pele examples/flowchart.mmd -o flowchart.svg && echo $?
0
$ pele examples/flowchart.mmd -o flowchart.png --scale 2

Theming

Pele styles diagrams with CSS variables (--pele-bg, --pele-fg, ...). The CLI emits standalone SVG, so set the variables in the SVG's context or via inline style on a container. See the Pele theming docs.

Releasing (maintainers)

Publishing is automated by .github/workflows/publish.yml using npm trusted publishing (OIDC). No token is stored in GitHub; the published tarball carries provenance.

One-time setup on npmjs.com (needs the account that owns @simhozebs/pele-cli):

1. Package settings → Trusted providers → GitHub Actions.
2. Repository SimHoZebs/pele-cli, workflow filename publish.yml.

Cut a release:

npm version patch   # or minor / major; commits and tags
git push origin main --follow-tags

The workflow checks the v* tag matches package.json's version, runs npm test and bun test, and publishes with --access=public --provenance. A workflow_dispatch trigger is also available and publishes the current package.json version (fails loudly if that version is already on the registry).

Development

Requires Bun (for bun check / bun build) and Node.js (for the node --test pass; Bun runs its own pass too).

npm install
npm test          # bun check + build + node --test
npm run test:bun  # bun check + build + bun test

src/pele.ts is the entry point; the logic lives in src/cli-core.ts and is exercised through run(args, io) with injected I/O. bin/pele.js is a committed shim with the executable shebang (bun build --no-bundle strips it); it imports dist/pele.js for its side effect. The published package ships bin/ + dist/ only, so consumers need no TypeScript or Bun tooling. prepack rebuilds before npm pack/npm publish.

License

MIT. See LICENSE. Pele is MIT licensed by the Obsidian team.