Use the CLI

Command line troubleshooting

What a message from the command line means and what to do about it. Most failures are one of the rows below.

TL;DR

Question	Answer
The check says a picture is stale, but I changed nothing	The pictures were drawn by another release or with other settings. Run `sync` with the release the check pins, and commit what it writes.
A glob matches nothing	Quote it, such as `"docs/*/.md"`, and run from the repository root.
It says my Node is too old	Install Node 22 or newer.
Where do I see every option?	`plotwork <command> --help`, or the Command reference.

Stale pictures and drift

Message	Cause	Fix
`stale: README.md needs sync`	The source of a fence changed and its picture did not, or the picture was drawn by another release or with other defaults.	Run `sync` on the file with the same release and settings as the check, and commit the Markdown and the SVGs.
`stale` in CI, `up to date` on your machine	The check pins one release and your machine ran another, or CI found a different settings file.	Run the exact command of the CI step, with its pinned version, from the repository root.
`drift: docs/infra.diagram`	The files a generated diagram is made from changed. The lines under it name each node and edge added, removed, or changed.	Run `generate` and commit what it writes. Change the diagram in its overrides file, never in the generated file. See Diagrams as code.
A hand edit of a generated diagram is undone	`generate` writes over the generated file.	Run `generate --capture` after the edit, which moves it to the overrides file, then `generate`.

Usage mistakes, exit code 2

Message	Cause	Fix
`no Markdown file matches docs/*.md`	The glob matched nothing from the working directory, or the shell expanded it first.	Quote the glob, and check the folder you run in.
`Unknown option '--colour'`	The option is not one the command takes. The help follows the message.	Run `plotwork <command> --help` for the options.
`no settings: add plotwork.config.json with a sources section`	`generate` found no settings file.	Add the file, or pass `--config <file>`.
`no rules: add a rules section to plotwork.config.json`	`check` found no rules.	Add a `rules` section, or pass `--org` with `PLOTWORK_API_KEY`.
A settings error with a line and a caret	The settings file does not check against its schema.	Fix the line it names. Add `$schema` to the file so your editor shows the mistake as you type.
`generate --out writes a report, so it needs --format json, sarif, or junit`	`--out` was given for text or github output.	Add a report format, or leave out `--out`.

Diagram mistakes, exit code 1

Each mistake has a code, a line and column, and a hint. The hint is the fix: apply it and run the command again. Every code is listed in Diagnostics. validate --strict also fails on warnings, such as a label too long to read; leave out --strict to report them without failing.

Installing and running

Symptom	Cause	Fix
`plotwork needs Node 22 or newer`	An older Node runs the command.	Install Node 22 or newer, or use the `node:22` image in CI.
`npx` asks to install the package	`-y` is missing.	Add `-y` (or `--yes`) after `npx`, as every sample does.
`npm error 404` for the version	The version is not on npm, or a private registry does not mirror it.	Check the version on npm (opens in a new tab), and mirror it into your registry.
A product icon is drawn as a plain shape	`PLOTWORK_VENDOR_ICONS=off` is set.	Unset it. See Environment variables.

Reading a picture

Message	Cause	Fix
The picture carries no source	It was drawn with `--no-embed-source`, or by a tool that leaves the source out. `read` prints its title and labels instead.	Draw it again with the source embedded, or write the source again from the labels. See Editing an existing diagram.
A hosted link cannot be read	The link is wrong, deleted, or private to an organisation.	Open the link in a browser to check it.

Doc	Why
Exit codes and output formats	What each code means for each command
CI usage	The step for each CI system
Configuration	How the settings file is found