CLI

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

Do it with an agent

Paste into your AI coding agent:

Render every diagram in this repo. If diagramkit is not installed yet, install it with npm add diagramkit and run npx diagramkit warmup unless the repo is Graphviz-only. Read node_modules/diagramkit/llms.txt for defaults. Run npx diagramkit render . and report any failures with their file path.

For a repeatable script, ask the agent to add "render:diagrams": "diagramkit render ." to package.json.

Do it manually

The rest of this page is the manual reference: how to invoke the CLI, every command, every flag, examples, and exit codes. Skim the section that matches what you’re trying to do.

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()3diagramkit init --yes    # accept defaults, non-interactive

The generated diagramkit.config.json5 includes a $schema reference so editors (VSCode, JetBrains, etc.) offer autocomplete out of the box. The schema ships in the npm package at diagramkit/schemas/diagramkit-config.v1.json.

`validate`

Validate generated SVG file(s) for structural correctness and <img>-tag renderability. Use after render (especially in CI) to catch SVGs with missing xmlns, missing dimensions, embedded <script>, broken <foreignObject>, or external resource references that silently fail in <img> embeds.

1diagramkit validate <file-or-dir> [--recursive] [--json]

Examples:

1diagramkit validate .diagramkit/                # all SVGs in a folder (top level)2diagramkit validate .diagramkit/ --recursive    # recurse into subfolders3diagramkit validate output.svg                  # single file4diagramkit validate . --recursive --json        # CI-friendly machine-readable output

Exits non-zero when any SVG fails. The directory render and single-file render commands also run this check automatically and surface results inline.

Interactive wizards

When run on a TTY without enough arguments, the CLI launches a top-level interactive picker (render / validate / init / doctor / warmup). Inside render and validate it then walks you through targets, formats, and theme — seeded from the effective diagramkit.config.* it auto-discovers from the cwd.

1diagramkit                              # top-level picker (TTY)2diagramkit render --interactive         # force the render wizard, even with args3diagramkit render . --no-interactive    # disable the wizard for CI/agents4diagramkit render . --yes               # alias for --no-interactive (accept defaults)

--interactive falls back with a one-line warning when stdout is not a TTY (so CI logs stay clean).

Project skills (the diagramkit CLI does not install them)

Important

The previous diagramkit --install-skill flag was removed in v0.3. Skills now ship inside the npm package at node_modules/diagramkit/skills/<name>/SKILL.md. The diagramkit-setup skill writes thin pointer SKILL.md files into your repo (.agents/skills/diagramkit-* plus harness mirrors under .claude/skills/, .cursor/skills/, .codex/skills/) that defer to those bundled originals — so every agent reads guidance pinned to the installed CLI version.

Recommended (local pointers):

1npm add diagramkit2# Then have your agent follow:3#   node_modules/diagramkit/skills/diagramkit-setup/SKILL.md4# It writes pointer SKILL.md files for: setup, auto, mermaid, excalidraw,5# draw-io, graphviz, review (validation + WCAG 2.2 AA contrast).

Alternative (GitHub-published skills via the standalone skills CLI), when you want skills that update independently of the installed diagramkit:

1npx skills add sujeet-pro/diagramkit                               # all skills2npx skills add sujeet-pro/diagramkit -a claude-code -a cursor -a codex3npx skills add sujeet-pro/diagramkit -s diagramkit-setup -s diagramkit-review4npx skills update sujeet-pro/diagramkit                            # refresh later

Pick one mechanism per repo (local pointers OR npx skills) so they don’t drift against each other.

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     # exit non-zero if any single render fails8diagramkit render . --strict-config9diagramkit render . --max-type-lanes 2

--strict (render-failure strictness) is independent of --strict-config (config-validation strictness). Use --strict when you want CI to fail loudly on a single broken diagram rather than just printing it to the failure list.

Global Flags

1diagramkit --help              # show help2diagramkit -h3diagramkit --version           # show version4diagramkit -v5diagramkit --agent-help        # output full reference for LLM agents6diagramkit --interactive       # force interactive wizard even when args are present (TTY required)7diagramkit -i                  # short form8diagramkit --no-interactive    # disable interactive wizard (useful for CI / agents)9diagramkit --yes               # alias for --no-interactive (accept defaults)10diagramkit -y                  # short form

Project skills are installed by the diagramkit-setup skill as local pointers into node_modules/diagramkit/skills/ (default), or by the standalone skills CLI (npx skills add sujeet-pro/diagramkit) when the repo prefers GitHub-published skills. See 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).