# Exit codes and output formats

> Page: https://docs.plotwork.dev/cli/exit-codes-and-output. Index of every page: https://docs.plotwork.dev/llms.txt

What each exit code of the command line means, for every command, and what each `--format` prints. A script or a CI step reads the code; a person reads the text; a code scanner or a test view reads a report.

## TL;DR

| Question | Answer |
|---|---|
| What are the exit codes? | `0` all is well, `1` a problem in a diagram, `2` a mistake in the command line. |
| Why two failure codes? | A CI step fails on both, and a script can tell a diagram that needs fixing from a command that needs fixing. |
| Where do mistakes go? | Standard error, each with its file, line, column, code, and a hint. Standard output holds the result: a source, a report, or a summary line. |
| Which formats are there? | `text` (the default), `github`, `json`, `sarif`, and `junit`, each on the commands that take it. `export` has its own formats for wikis. |
| Is the JSON report stable? | Yes. It carries a version, and its JSON Schema is published. A change that breaks a reader gets a new version. |

## Exit codes

| Code | Meaning | Examples |
|---|---|---|
| `0` | All is well. | Every picture is current, every diagram is valid, the source was written. |
| `1` | A problem in a diagram. | A stale or missing picture, a syntax error, a broken style rule, a generated diagram that drifted, a picture with no source to read. |
| `2` | A mistake in the command line. | An unknown option, a missing operand, a glob that matches nothing, a settings file that does not check, `generate` with no `sources`. |

Each command says what the codes mean for it:

For every command, code `2` is 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. The last column says what else it means for that command.

| Command | 0 | 1 | 2 |
|---|---|---|---|
| [`sync`](https://docs.plotwork.dev/cli/commands/sync.md) | Every picture is current (with `--check`), or every picture was written. | A picture is stale (with `--check`), or a diagram has a mistake and was not drawn. | Nothing more. |
| [`validate`](https://docs.plotwork.dev/cli/commands/validate.md) | Every diagram is valid. | A diagram has an error, or a warning with `--strict`. | Nothing more. |
| [`check`](https://docs.plotwork.dev/cli/commands/check.md) | No rule at level error is broken. | A rule at level error is broken, a diagram has an error, or the saved rules could not be read. | Also when no rules are found, or `--org` is given with no key. |
| [`render`](https://docs.plotwork.dev/cli/commands/render.md) | The SVG was written. | The diagram has an error, or the file holds no diagram. | Nothing more. |
| [`read`](https://docs.plotwork.dev/cli/commands/read.md) | The source was printed or written. | The picture carries no source, the source has errors, or a hosted link could not be read. | Nothing more. |
| [`outline`](https://docs.plotwork.dev/cli/commands/outline.md) | Every diagram was outlined. | A diagram has an error. | Nothing more. |
| [`generate`](https://docs.plotwork.dev/cli/commands/generate.md) | Every diagram is in step (with `--check`), or every diagram was written. | A diagram drifted (with `--check`), or a diagram has an error. | Also when there are no settings, no sources, or `--since` names a ref git does not know. |
| [`import-source`](https://docs.plotwork.dev/cli/commands/import-source.md) | The source was printed or written. | Nothing could be imported from the file. | Also when the format or a value of `--view`, `--chart`, or `--group-by` is not one it knows. |
| [`import`](https://docs.plotwork.dev/cli/commands/import.md) | Everything converted. | A diagram or a fence could not be converted, or the file could not be read. | Also when the file is not `.mmd`, `.mermaid`, or Markdown. |
| [`export`](https://docs.plotwork.dev/cli/commands/export.md) | The text was printed or written. | The diagram has an error. | Also when `--format` is missing or `--image` is not an https address. |
| [`publish`](https://docs.plotwork.dev/cli/commands/publish.md) | Every diagram was saved, and its link printed. | A diagram has a mistake (nothing is sent), the API refused one (its code and words are printed), or the API could not be reached. | Also when `PLOTWORK_API_KEY` is missing or refused, `--personal` and `--org` are both given, or `--alias` is given for a file with several diagrams. |
| [`icons`](https://docs.plotwork.dev/cli/commands/icons.md) | The search ran, whether or not anything matched. | Not used. | No query was given. |

## Output formats

| Format | Commands | What it prints |
|---|---|---|
| `text` | `sync`, `check`, `generate`, `import-source`, `import` | Lines a person reads. Mistakes go to standard error with a line, a column, and a hint. |
| `github` | `sync`, `check`, `generate` | GitHub workflow commands: each problem is an `::error` or `::warning` annotation on its file and line in the pull request. |
| `json` | `generate`, `import-source`, `import` | One JSON document on standard output, for a script. `generate` writes its versioned report, whose JSON Schema is at `https://docs.plotwork.dev/schemas/plotwork.report.json`. |
| `sarif` | `generate` | A SARIF 2.1.0 report for code scanning, such as GitHub code scanning or Azure DevOps. |
| `junit` | `generate` | A JUnit XML report: one test case for each source, failed when its diagram drifted or has an error, for the test view of GitLab, Jenkins, CircleCI, or Azure Pipelines. |
| `confluence` | `export` | Confluence storage format (XHTML): the format of Confluence's REST API and of a page's source in Data Center. |
| `confluence-wiki` | `export` | Confluence wiki markup, which the Cloud editor takes through Insert, then Markup. |
| `notion` | `export` | Markdown that Notion turns into an image block and a code block when it is pasted. |

### text

The default. Each mistake is printed as the engine reports it: the code, the message, the line of the diagram with a caret under the column, and a hint. Under it, `at file line` names the line in the file, so an editor can jump to it. The last line is a summary, such as `up to date: README.md` or `ok: 3 diagram(s) checked, 0 drifted, 0 error(s)`.

### github

[GitHub workflow commands](https://docs.github.com/actions/reference/workflow-commands-for-github-actions). A line such as the one below becomes an error on line 12 of the file in the pull request's Files changed tab:

```text
::error file=docs/architecture.md,line=12,title=Stale diagram::The picture under this diagram is missing or out of date.
```

The file is named from the working directory, which in a workflow is the repository root. Run the command from the root, or the annotations will not find their files.

### json

One JSON document on standard output and nothing else, so it can be piped to `jq`. `import` and `import-source` print the conversion with its diagnostics. `generate` prints its versioned report: each diagram, whether it drifted, what changed by meaning, its CODEOWNERS owners, and where the run happened. The schema is at [plotwork.report.json](https://docs.plotwork.dev/schemas/plotwork.report.json).

### sarif and junit

Reports from `generate` for tools that already show findings. SARIF goes to code scanning, where a drifted diagram is an alert on its file. JUnit goes to a test view: each source is a test case that fails when its diagram drifted or has an error. With `--out <file>` the report is written to the file and the terminal gets the text a person reads, so the log still says what drifted.

## See also

| Doc | Why |
|---|---|
| [CI usage](https://docs.plotwork.dev/cli/ci.md) | Each format in a pipeline |
| [Command reference](https://docs.plotwork.dev/cli/commands.md) | Every command and its options |
| [Troubleshooting](https://docs.plotwork.dev/cli/troubleshooting.md) | What to do about a failure |