# Command line quick start

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

From an empty page to a diagram that CI keeps in step, in five steps. You need Node 22 or newer and a repository with a Markdown file.

## TL;DR

| Question | Answer |
|---|---|
| What do I install? | Nothing. `npx` fetches the pinned release the first time and keeps it in its cache. |
| What do I write? | A `diagram` fence in a Markdown file. |
| What draws it? | `npx -y @buun_group/plotwork@0.1.0 sync README.md`, which writes a light and a dark SVG and the picture block under the fence. |
| What do I commit? | The Markdown file and the SVGs it wrote. |
| What fails CI? | `sync --check`, when the source changed and the picture did not. |

## 1. Write a diagram

Add a fence to `README.md`:

````md
```diagram
flow "Checkout" direction=down
node shop service "Shop"
node pay service "Payments"
node db database "Orders DB"
shop -> pay : "charge"
pay -> db : "record"
```
````

The fence is the source. The language is in [Writing diagrams](https://docs.plotwork.dev/writing-diagrams.md), and the [Language reference](https://docs.plotwork.dev/reference/language.md) has every statement.

## 2. Check it

```sh
npx -y @buun_group/plotwork@0.1.0 validate README.md
```

A mistake prints its line and column in the file, a code, and a hint that says how to fix it. The command exits 0 when every diagram is valid and 1 when one is not.

## 3. Draw it

```sh
npx -y @buun_group/plotwork@0.1.0 sync README.md
```

`sync` writes `assets/diagrams/checkout.svg` and `checkout.dark.svg` beside the page, named after the diagram's title. It folds the fence into a "Diagram source" block and writes a picture block under it that shows the light or the dark picture to match the reader's theme, with a text description for a screen reader. GitHub, GitLab, and every Markdown viewer show the picture, and the fence stays in the page as the source. [Markdown and GitHub](https://docs.plotwork.dev/markdown-and-github.md) shows what the block looks like.

Run `sync` again after any change to the source. A fence whose picture is already current is left alone.

## 4. Commit both

```sh
git add README.md assets/diagrams
git commit -m "docs: add the checkout flow"
```

## 5. Check it in CI

Add one step to your pipeline:

```sh
npx -y @buun_group/plotwork@0.1.0 sync --check README.md "docs/**/*.md"
```

It writes nothing and exits 1 when a picture is missing or older than its source, or a diagram has a mistake, so a pull request that changes a diagram without redrawing it fails. Quote a glob so the command line expands it the same way in every shell. [CI usage](https://docs.plotwork.dev/cli/ci.md) has the step for GitHub Actions, GitLab CI, Azure Pipelines, Jenkins, and CircleCI.

## Next

| To | Run |
|---|---|
| Set defaults, such as the direction of every flow, for the whole repository | Add `plotwork.config.json`. See [Configuration](https://docs.plotwork.dev/cli/configuration.md). |
| Draw your Terraform, OpenAPI, or database schema and keep it in step | `plotwork generate`. See [Diagrams as code](https://docs.plotwork.dev/diagrams-as-code.md). |
| Move Mermaid diagrams to Plotwork | `plotwork import README.md --write`. See [Migrating from Mermaid](https://docs.plotwork.dev/migrating-from-mermaid.md). |
| Change a picture you already have | `plotwork read picture.svg > picture.diagram`. See [Editing an existing diagram](https://docs.plotwork.dev/editing-existing-diagrams.md). |

## See also

| Doc | Why |
|---|---|
| [Overview](https://docs.plotwork.dev/cli/overview.md) | npx or install, and what each command is for |
| [Command reference](https://docs.plotwork.dev/cli/commands.md) | Every command, option, and default |
| [Troubleshooting](https://docs.plotwork.dev/cli/troubleshooting.md) | When a step does not do what this page says |