wavedrom-cli

3.2.0 verified Sat Apr 25 auth: no javascript maintenance

WaveDrom command-line interface for converting digital timing diagrams defined in JSON5/JS object notation into SVG or PNG images. Current stable version is 3.2.0, requiring Node.js >=12 (recommended v14+). It supports rendering signal groupings and outputs SVG natively; PNG export uses the native SVG renderer. Unmaintained for some time (last significant release v0.3.x), with breaking changes from prior versions that relied on PhantomJS. Key differentiator: enables programmatic and CI-based generation of timing diagrams without a browser.

Common errors

error Error: Cannot find module 'wavedrom-cli' ↓

cause Global install not found or npx not used.

fix

Install globally with npm i -g wavedrom-cli or use npx wavedrom-cli.

error SyntaxError: Unexpected token '.' ↓

cause JSON5 file contains JavaScript syntax that is not valid JSON5.

fix

Use valid JSON5 (e.g., keys unquoted allowed, but no trailing commas).

Warnings

gotcha Node.js version: v14+ required. Lower versions may fail with SyntaxError or missing features. ↓

fix Upgrade Node.js to v14 or later. Use nvm or similar.

breaking PhantomJS-based versions (<=0.2.0) are completely different and incompatible with the current CLI. Do not mix. ↓

fix Uninstall PhantomJS and use the npm package directly.

deprecated The --png option uses native SVG-to-PNG conversion which may produce low-quality output. Consider using Inkscape for PNG export. ↓

fix Pipe SVG output to Inkscape: `wavedrom-cli -i input.json5 | inkscape -p --export-filename=output.png`

Install

npm install wavedrom-cli

yarn add wavedrom-cli

pnpm add wavedrom-cli

Imports

none (CLI only)

wrong

npx wavedrom-cli -i input.js -s output.png

correct

npx wavedrom-cli -i input.json5 -s output.svg

This is a CLI tool, not a library. Use npx or global install.

Quickstart

Create a timing diagram from a JSON5 source file and export to SVG using wavedrom-cli.

mkdir wavedrom-example && cd wavedrom-example
cat > timing.json5 << 'EOF'
{
  signal: [
    { name: "clk", wave: "p.....|" },
    { name: "data", wave: "x...345x|" },
    { name: "addr", wave: "x...2x|" }
  ]
}
EOF
npx wavedrom-cli -i timing.json5 -s timing.svg