# The Plotwork command line

> Page: https://docs.plotwork.dev/cli/overview. Index of every page: https://docs.plotwork.dev/llms.txt

`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.

## 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](https://docs.plotwork.dev/cli/commands.md), 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`](https://docs.plotwork.dev/cli/commands/sync.md) |
| Fail CI when a picture is stale | [`plotwork sync --check`](https://docs.plotwork.dev/cli/commands/sync.md) |
| Check a diagram for mistakes, with a line, a column, and a hint | [`plotwork validate`](https://docs.plotwork.dev/cli/commands/validate.md) |
| Fail CI when a diagram breaks your team's style rules | [`plotwork check`](https://docs.plotwork.dev/cli/commands/check.md) |
| Draw one diagram to an SVG | [`plotwork render`](https://docs.plotwork.dev/cli/commands/render.md) |
| Get the source back from a picture | [`plotwork read`](https://docs.plotwork.dev/cli/commands/read.md) |
| Make diagrams from Terraform, OpenAPI, Compose and other files, and fail CI on drift | [`plotwork generate`](https://docs.plotwork.dev/cli/commands/generate.md) |
| Draw one file of another format once | [`plotwork import-source`](https://docs.plotwork.dev/cli/commands/import-source.md) |
| Convert Mermaid | [`plotwork import`](https://docs.plotwork.dev/cli/commands/import.md) |
| Paste a diagram into Confluence or Notion | [`plotwork export`](https://docs.plotwork.dev/cli/commands/export.md) |

## 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](https://docs.plotwork.dev/diagrams-in-ci.md) 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](https://docs.plotwork.dev/cli/ci.md) 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](https://docs.plotwork.dev/cli/environment.md) lists everything it reads.

## See also

| Doc | Why |
|---|---|
| [Quick start](https://docs.plotwork.dev/cli/quick-start.md) | A first diagram, from a fence to a checked pull request |
| [Command reference](https://docs.plotwork.dev/cli/commands.md) | Every command, option, and default |
| [CI usage](https://docs.plotwork.dev/cli/ci.md) | GitHub Actions, GitLab CI, Azure Pipelines, Jenkins, and CircleCI |
| [Configuration](https://docs.plotwork.dev/cli/configuration.md) | The repository settings every command reads |
| [MCP server](https://docs.plotwork.dev/mcp/overview.md) | The same engine for an AI agent |