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]2                     [--max-width <px> | --no-max-width]3                     [--scope-dir <name>] [--fail-on <CODE,...>] [--fail-on-severity <warn|error>]

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 output5diagramkit validate . --recursive --scope-dir diagrams          # only SVGs under diagrams/ folders6diagramkit validate . --recursive --fail-on LOW_CONTRAST_TEXT   # promote a warning to fatal7diagramkit validate . --recursive --fail-on-severity warn       # fail on any warning or error

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

Policy flags (compose with each other; the baseline — any error-severity issue — always fails):

--scope-dir <name> — only consider SVGs under a directory segment named <name> (e.g. diagrams), so hand-authored assets elsewhere in the tree stop producing false-positive warnings. No-op when the target is a single file.
--fail-on <CODE,...> — promote specific issue codes to fatal. Unknown codes are dropped with a warning rather than failing the command. Valid codes: EMPTY_FILE, MISSING_SVG_TAG, MISSING_SVG_CLOSE, MISSING_WIDTH, MISSING_HEIGHT, NO_VISUAL_ELEMENTS, CONTAINS_SCRIPT, CONTAINS_FOREIGN_OBJECT, MISSING_XMLNS, EXTERNAL_RESOURCE, INVALID_VIEWBOX, SVG_TOO_LARGE, LOW_CONTRAST_TEXT, ASPECT_RATIO_EXTREME, SVG_VIEWBOX_TOO_WIDE.
--fail-on-severity <warn|error> — fail if any issue at or above this severity exists.

--json emits a versioned envelope (schemaVersion: 1) including the effective policy, any promoted warnings, and the overall failed disposition — see CLI Reference → JSON Envelope — validate. Schema: diagramkit/schemas/diagramkit-cli-validate.v1.json.

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 (`diagramkit skills install`)

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 default install is the skills install subcommand, which writes thin pointer SKILL.md files into your repo (.agents/skills/diagramkit-* plus harness mirrors under .claude/skills/, .cursor/skills/, .codex/skills/, .continue/skills/) that defer to those bundled originals — so every agent reads guidance pinned to the installed CLI version.

Recommended (CLI installer):

1npm add diagramkit2npx diagramkit skills install3# Writes pointer SKILL.md files for: setup, auto, mermaid, excalidraw,4# draw-io, graphviz, review (validation + WCAG 2.2 AA contrast).

1diagramkit skills install --harness claude,cursor      # explicit harness set2diagramkit skills install --only mermaid --only review # restrict to specific skills3diagramkit skills install --dry-run                    # preview, write nothing4diagramkit skills install --check --json               # CI drift gate, machine-readable

Re-runs are idempotent (created/updated/unchanged per stub) and sweep stubs left by a removed skill, scoped to the diagramkit-* namespace. See CLI Reference → skills install Options for the full flag table. The diagramkit-setup skill documents the same pointer format as a prose fallback for contexts where the CLI can’t run.

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 (diagramkit skills install 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 npx diagramkit skills install (default) as local pointers into node_modules/diagramkit/skills/, 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).