CLI

The CLI is the recommended way to use diagramkit. It handles file discovery, incremental builds, watch mode, and output naming automatically.

Invocation Paths

After installation, these entrypoints all invoke the same CLI:

1npx diagramkit --version2./node_modules/.bin/diagramkit --version3node ./node_modules/diagramkit/dist/cli/bin.mjs --version

Use whichever form fits your environment. Local npm bin shims and direct dist/cli/bin.mjs execution behave the same as npx diagramkit.

Commands

`render`

Render one or more diagram files to images.

1diagramkit render <file-or-dir> [options]

A file renders that single diagram. A directory recursively discovers and renders all diagram files.

1# Render all diagrams in the current directory2diagramkit render .34# Render a single file5diagramkit render docs/architecture.mermaid67# Render a specific directory8diagramkit render ./content/posts

`warmup`

Pre-install the Playwright Chromium browser binary. Run once per environment.

1diagramkit warmup

`doctor`

Validate environment readiness (Node, Playwright, Chromium, sharp):

1diagramkit doctor2diagramkit doctor --json

`init`

Create a config file in the current directory.

1diagramkit init          # diagramkit.config.json52diagramkit init --ts     # diagramkit.config.ts with defineConfig()

`--install-skill`

Install project-level skills for Claude and Cursor in the current repository.

1diagramkit --install-skill

This writes .claude/skills/diagramkit/SKILL.md and .cursor/skills/diagramkit/SKILL.md if they do not already exist. The generated skill tells agents to read node_modules/diagramkit/llms.txt, add a render:diagrams script, and create diagramkit.config.json5 only when the repo needs non-default behavior.

Render Options

Output Format

1diagramkit render . --format svg      # default2diagramkit render . --format png3diagramkit render . --format jpeg4diagramkit render . --format webp5diagramkit render . --format avif6diagramkit render . --format svg,png  # multiple formats in one pass

Tip

PNG, JPEG, WebP, and AVIF require sharp. Install with npm add sharp.

Theme

1diagramkit render . --theme both      # default -- produces -light and -dark variants2diagramkit render . --theme light     # light only3diagramkit render . --theme dark      # dark only

Scale and Quality (Raster Only)

1diagramkit render . --format png --scale 3       # 3x resolution for HiDPI2diagramkit render . --format jpeg --quality 80    # compression quality 1-1003diagramkit render . --format webp --quality 85 --scale 2

Force Re-render

1diagramkit render . --force      # ignore manifest cache, re-render everything2diagramkit render . -f           # short form

Watch Mode

1diagramkit render . --watch      # watch for changes, re-render on save2diagramkit render . -w           # short form

See Watch Mode for details.

Dark Mode Contrast

1diagramkit render . --no-contrast    # skip WCAG contrast optimization on dark SVGs

By default, dark-mode Mermaid and Graphviz SVGs are post-processed to fix fill colors with poor contrast.

Filter by Type

1diagramkit render . --type mermaid2diagramkit render . --type excalidraw3diagramkit render . --type drawio4diagramkit render . --type graphviz

Custom Output

1# Single file to a custom directory2diagramkit render diagram.mermaid --output ./build/images34# Change the output folder name (default: .diagramkit)5diagramkit render . --output-dir images67# Place outputs next to source files (no subfolder)8diagramkit render . --same-folder910# Add prefix/suffix to output filenames11diagramkit render . --output-prefix "dk-"12diagramkit render . --output-suffix "-v2"

When you use --output, diagramkit writes to that folder directly. Directory renders skip manifest tracking for that run, and single-file renders do not update the source directory manifest. Use --output-dir if you want custom folder naming while keeping incremental manifests.

Explicit Config File

1diagramkit render . --config ./custom.config.json5

Use --config to point at a specific config file instead of auto-discovery. Useful for CI or monorepo setups.

Manifest Control

1diagramkit render . --no-manifest                        # disable incremental caching2diagramkit render . --manifest-file custom-manifest.json # custom manifest filename

Scripting and CI

1diagramkit render . --dry-run    # preview what would render, without rendering2diagramkit render . --plan       # include stale reasons in plan output3diagramkit render . --quiet      # suppress info output, errors only4diagramkit render . --log-level warn5diagramkit render . --log-level verbose6diagramkit render . --json       # machine-readable JSON output7diagramkit render . --strict-config8diagramkit render . --max-type-lanes 2

Global Flags

1diagramkit --help       # show help2diagramkit -h3diagramkit --version    # show version4diagramkit -v5diagramkit --agent-help # output full reference for LLM agents6diagramkit --install-skill # install project skills

Examples

1# Render everything with defaults2diagramkit render .3diagramkit .    # alias for "render ."45# High-res PNGs for documentation6diagramkit render ./docs --format png --scale 378# Watch mode during development9diagramkit render . --watch1011# Only mermaid, force re-render12diagramkit render . --type mermaid --force1314# Graphviz DOT to dark-only SVG15diagramkit render dependency.dot --theme dark1617# Single file to a custom folder18diagramkit render flow.mermaid --output ./static/images1920# Explicit config file for CI21diagramkit render . --config ./ci.config.json52223# CI: JSON output, no caching24diagramkit render . --json --no-manifest2526# CI: explain stale reasons before rendering27diagramkit render . --plan --json

JSON Contract Upgrade

--json now emits a versioned envelope with schemaVersion: 1 and nested result.
If you parsed legacy root-level JSON fields directly, migrate to result.*.

JSON schema: diagramkit/schemas/diagramkit-cli-render.v1.json (exported from the npm package).

Exit Codes

Code	Meaning
`0`	Success
`1`	Error (unknown command, render failure, etc.)

In watch mode, the process stays running until Ctrl+C (SIGINT).