Command reference

plotwork generate

Make the diagrams the settings' sources name from their files; --check fails on drift. It is a command of the Plotwork command line, the npm package @buun_group/plotwork.

TL;DR

Question	Answer
What does it do?	Make the diagrams the settings' sources name from their files; `--check` fails on drift.
How do I run it?	`npx -y @buun_group/plotwork@0.1.0-beta.13 generate`, or `plotwork generate` once the package is installed.
What does it write?	The diagrams and their pictures, unless `--check` is given; a report with `--out`.
Does it use the network?	No. `--since` runs git on this machine, which reads the history and fetches nothing.
Does it read the repository settings?	Yes: the header defaults of the settings file apply to every diagram. See Configuration.
How do I read this in a terminal?	`plotwork generate --help`

Synopsis

plotwork generate [--check] [--capture] [--source <name>] [--since <ref>] [--format text|github|json|sarif|junit] [--out <file>] [--config <file>]

What it does

Makes each diagram the sources of the settings file name from files of the repository (Terraform, OpenAPI, Compose, Kubernetes, Prisma, SQL, workflows, and more), applies its overrides file, and writes the .diagram file or the Markdown fence with its pictures.

With --check it writes nothing and exits 1 when a diagram has drifted from its files, naming each node and edge that was added, removed, or changed. --capture first keeps hand edits of a generated diagram in its overrides file, so the next run does not undo them.

Everything runs on this machine: nothing is fetched and no code in the files is run. --since asks git which files changed.

Options

Option	Default	What it does
`--check`	Off	Write nothing; exit 1 when a diagram drifted from its files.
`--capture`	Off	Keep hand edits of each generated diagram in its overrides file first.
`--source <name>`	every source	Only the source of this name.
`--since <ref>`	every source	Only the sources whose files changed since a git ref, such as `origin/main`.
`--format text\|github\|json\|sarif\|junit`	`text`	`github` prints annotations; `json`, `sarif`, and `junit` print a report.
`--out <file>`	standard output	Write the `json`, `sarif`, or `junit` report to a file, and print the text a person reads.
`--config <file>`	`PLOTWORK_CONFIG`, else the nearest `plotwork.config.json` or `.plotwork/config.json` from the file up to the repository root	The repository settings file to read: header defaults, and the style rules check applies.

Examples

Make every diagram the settings name, and write them.

plotwork generate

Fail when a diagram whose files changed on this branch has drifted.

plotwork generate --check --since origin/main

Write a report for code scanning, and print the summary.

plotwork generate --check --format sarif --out plotwork.sarif

Exit codes

Code	When
`0`	Every diagram is in step (with `--check`), or every diagram was written.
`1`	A diagram drifted (with `--check`), or a diagram has an error.
`2`	A mistake in the command line: an unknown option, a missing operand, a file or glob that matches nothing, or a settings file that cannot be read. Also when there are no settings, no sources, or `--since` names a ref git does not know.

Doc	Why
Command reference	Every command of the command line
Diagrams as code	Sources, overrides, and drift in full
CI usage	The drift check in every CI system
Repository settings	The sources section
Exit codes and output formats	What every code and format means