# Command line configuration

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

How the command line finds your repository settings, which commands use which part of them, and how an option on the command line and a setting combine. The fields of the file are in [Repository settings](https://docs.plotwork.dev/repository-settings.md); this page is about how `plotwork` reads it.

## TL;DR

| Question | Answer |
|---|---|
| Where does the file go? | `plotwork.config.json` at the repository root, or `.plotwork/config.json`. |
| How is it found? | `--config <file>`, else the file `PLOTWORK_CONFIG` names, else the nearest `plotwork.config.json` or `.plotwork/config.json` from the diagram's folder up to the folder that holds `.git`. |
| Is a file required? | No. Without one, every command draws with the built-in defaults. Only `check` needs `rules`, and `generate` needs `sources`. |
| Does an option on the command line win? | Yes. A flag wins over the settings, and the settings win over the built-in defaults. A diagram's own header wins over the settings' defaults. |
| What else is configured? | Only environment variables, listed in [Environment variables](https://docs.plotwork.dev/cli/environment.md). There is no other file and no per-user setting. |

## 1. A minimal file

```json
{
  "$schema": "https://docs.plotwork.dev/schemas/plotwork.config.json",
  "defaults": {
    "direction": "down",
    "icons": "auto"
  },
  "rules": {
    "requireTitle": true,
    "maxNodes": 40
  }
}
```

With `$schema`, an editor completes the fields and underlines a mistake. The file needs no account and is never sent anywhere.

## 2. Which commands read what

| Section | Read by | What it does there |
|---|---|---|
| `defaults` | `sync`, `validate`, `check`, `render`, `outline`, `generate` | Fills each header option a diagram leaves out, before the diagram is checked or drawn. |
| `rules` | `check` | The style rules the diagrams are checked against. `--org` replaces them with an organisation's saved rules; the defaults still apply. |
| `sources` | `generate` | The diagrams made from files of the repository. See [Diagrams as code](https://docs.plotwork.dev/diagrams-as-code.md). |
| `brand` | None | Read by hosted calls only. The command line draws in the built-in themes. |

`read`, `import`, `import-source`, `export`, and `icons` read no settings.

## 3. How the file is found

Each command looks for the settings of each file it reads, in this order, and uses the first it finds:

| Order | Where | Use it for |
|---|---|---|
| 1 | `--config <file>` | One run with other settings, such as a stricter rule set in CI. |
| 2 | The file `PLOTWORK_CONFIG` names | A CI job or a shell that always uses the same file. |
| 3 | `plotwork.config.json`, then `.plotwork/config.json`, in the file's folder and each folder above it, up to the folder that holds `.git` | The usual case: one file at the root of the repository. |

Because the search starts at each file, a repository of many packages can keep a settings file in a package's folder, and `sync "**/*.md"` applies the nearest one to each page. `generate` reads one file: the first found from the working folder up, and the paths in its `sources` start from that file's folder.

A file that does not check stops the command with exit code 2, and each problem is printed with its line and column in the file.

## 4. Options and settings together

| What | Order, first wins |
|---|---|
| A header option of a diagram, such as `direction` | The diagram's header, then `defaults`, then the built-in default |
| The theme of `render` | `--theme`, then `defaults.theme`, then `light` |
| Whether `render` embeds the source | `--no-embed-source`, then `defaults.embedSource`, then embedded |
| The pictures `sync` and `generate` write | A source's own `schemes`, then `defaults.schemes`, then `light-and-dark` (a light and a dark SVG); `auto` writes one SVG that follows the reader's setting |
| The rules of `check` | `--org` or `PLOTWORK_ORG`, then `rules` |

A change to `defaults` changes the pictures of every diagram that leaves those options out, so `sync --check` reports them stale until `sync` redraws them. Change the file and run `sync` in the same commit.

## See also

| Doc | Why |
|---|---|
| [Repository settings](https://docs.plotwork.dev/repository-settings.md) | Every field of the file, the rules, and sharing rules across repositories |
| [Environment variables](https://docs.plotwork.dev/cli/environment.md) | The variables the command line reads |
| [Diagrams as code](https://docs.plotwork.dev/diagrams-as-code.md) | The `sources` section and `generate` |
| [Command reference](https://docs.plotwork.dev/cli/commands.md) | Every option of every command |