The Plotwork command line
plotwork checks, draws, and syncs Plotwork diagrams in a repository, on your machine and in CI. It is the npm package @buun_group/plotwork, built from the same engine as the MCP server, the HTTP API, and the GitHub Action, so a picture it draws is the picture they draw.
- GitHub Actions
- GitLab
TL;DR
| Question | Answer |
|---|---|
| What does it do? | Draws the pictures under every diagram fence of your Markdown files, fails CI when one is stale, checks diagrams and style rules, makes diagrams from Terraform, OpenAPI, SQL and other files, converts Mermaid, and reads the source back out of a picture. |
| How do I run it? | npx -y @buun_group/plotwork@0.1.0-beta.13 <command>. Nothing to install beyond Node. |
| Which Node version? | Node 22 or newer. |
| Does it need an account or a key? | No. Only check --org, which reads an organisation's saved rules, needs a key. |
| Does it use the network? | Not by default. It reads and writes the files you name. read fetches a hosted link you give it, and check --org reads an organisation's rules; nothing else makes a request. |
| Does it count anything? | No. It keeps no usage counts and sends none. |
| Where is every command? | Command reference, one page for each command, and plotwork <command> --help in a terminal. |
| How is it different from the GitHub Action? | The Action runs the same engine inside GitHub Actions with inputs instead of flags. The command line runs anywhere Node runs: your machine, GitLab, Azure Pipelines, Jenkins, CircleCI. |
Run it with npx or install it
There are two ways to run it. Both run the same release.
| Way | Command | Use it when |
|---|---|---|
| npx, pinned | npx -y @buun_group/plotwork@0.1.0-beta.13 sync --check "docs/**/*.md" | In CI, and for a one-off run. Nothing is added to the project. |
| A dev dependency | npm install --save-dev --save-exact @buun_group/plotwork@0.1.0-beta.13, then npx plotwork sync | The project already has Node tooling, and you want the version in its lock file. |
| Installed for your user | npm install --global @buun_group/plotwork@0.1.0-beta.13, then plotwork sync | You run it often across many repositories. |
Pin the exact version everywhere. A new release can draw a picture a little differently, and a check that runs the latest release would then fail on a pull request that changed nothing. Move the pin in a change you review, and run sync in the same change.
plotwork --version prints the release, and plotwork --help lists every command.
What it does
| Job | Command |
|---|---|
| Draw the pictures under every diagram fence of a page, and keep them in step | plotwork sync |
| Fail CI when a picture is stale | plotwork sync --check |
| Check a diagram for mistakes, with a line, a column, and a hint | plotwork validate |
| Fail CI when a diagram breaks your team's style rules | plotwork check |
| Draw one diagram to an SVG | plotwork render |
| Get the source back from a picture | plotwork read |
| Make diagrams from Terraform, OpenAPI, Compose and other files, and fail CI on drift | plotwork generate |
| Draw one file of another format once | plotwork import-source |
| Convert Mermaid | plotwork import |
| Paste a diagram into Confluence or Notion | plotwork export |
Where it runs
On a developer's machine, plotwork sync redraws the pictures before a commit. In CI, plotwork sync --check and plotwork generate --check fail the build when a picture or a generated diagram is out of step. On GitHub the GitHub Action does the same with annotations on the pull request, and on GitLab and every other CI the command line does it with an exit code. CI usage has a pipeline for each.
Privacy
The command line runs on your machine and keeps nothing. It counts no use and sends no totals: PLOTWORK_USAGE and DO_NOT_TRACK, which control the local MCP server's opt-in counts, have no effect on it. The two requests it can make are the ones you ask for: read with a hosted link, and check --org. Environment variables lists everything it reads.
See also
| Doc | Why |
|---|---|
| Quick start | A first diagram, from a fence to a checked pull request |
| Command reference | Every command, option, and default |
| CI usage | GitHub Actions, GitLab CI, Azure Pipelines, Jenkins, and CircleCI |
| Configuration | The repository settings every command reads |
| MCP server | The same engine for an AI agent |