# plotwork generate

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

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 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](https://docs.plotwork.dev/cli/configuration.md). |
| How do I read this in a terminal? | `plotwork generate --help` |

## Synopsis

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

```sh
plotwork generate
```

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

```sh
plotwork generate --check --since origin/main
```

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

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

## See also

| Doc | Why |
|---|---|
| [Command reference](https://docs.plotwork.dev/cli/commands.md) | Every command of the command line |
| [Diagrams as code](https://docs.plotwork.dev/diagrams-as-code.md) | Sources, overrides, and drift in full |
| [CI usage](https://docs.plotwork.dev/cli/ci.md) | The drift check in every CI system |
| [Repository settings](https://docs.plotwork.dev/repository-settings.md) | The sources section |
| [Exit codes and output formats](https://docs.plotwork.dev/cli/exit-codes-and-output.md) | What every code and format means |