# plotwork check

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

Check every diagram against a team's style rules; fails on a broken rule at level error. It is a command of the Plotwork command line, the npm package `@buun_group/plotwork`.

## TL;DR

| Question | Answer |
|---|---|
| What does it do? | Check every diagram against a team's style rules; fails on a broken rule at level error. |
| How do I run it? | `npx -y @buun_group/plotwork@0.1.0 check`, or `plotwork check` once the package is installed. |
| What does it write? | Nothing. |
| Does it use the network? | No, unless `--org` or `PLOTWORK_ORG` names an organisation: then one request to the Plotwork API reads its rules, with the key in `PLOTWORK_API_KEY`. |
| 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 check --help` |

## Synopsis

```sh
plotwork check <files...> [--org <slug>] [--format text|github] [--config <file>]
```

## What it does

Checks every diagram of the files against style rules: required icons, naming patterns, allowed tones, a size budget, and forbidden kinds. The rules are the `rules` section of the repository settings file, or with `--org` the rules an organisation saved in Plotwork.

Each word is a Markdown or `.diagram` file, a folder, or a quoted glob. The header defaults of the settings are applied first, so a diagram is checked as it is drawn.

## Options

| Option | Default | What it does |
|---|---|---|
| `--org <slug>` | `PLOTWORK_ORG`, else the rules of the settings file | Check against the rules an organisation saved instead, read with the key in `PLOTWORK_API_KEY`. |
| `--format text\|github` | `text` | `github` prints each broken rule as a GitHub annotation on its line. |
| `--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

Check the docs and every diagram file under diagrams against the rules of the settings file.

```sh
plotwork check "docs/**/*.md" diagrams
```

Check against the organisation's saved rules in a GitHub workflow.

```sh
plotwork check --org acme --format github "**/*.md"
```

## Exit codes

| Code | When |
|---|---|
| `0` | No rule at level error is broken. |
| `1` | A rule at level error is broken, a diagram has an error, or the saved rules could not be read. |
| `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 no rules are found, or `--org` is given with no key. |

## See also

| Doc | Why |
|---|---|
| [Command reference](https://docs.plotwork.dev/cli/commands.md) | Every command of the command line |
| [Repository settings](https://docs.plotwork.dev/repository-settings.md) | The rules section and its checks |
| [Organisations](https://docs.plotwork.dev/organisations.md) | Rules saved for a whole organisation |
| [Exit codes and output formats](https://docs.plotwork.dev/cli/exit-codes-and-output.md) | What every code and format means |