# Environment variables

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

Every environment variable the command line reads, and the ones it ignores. A flag on the command line always wins over a variable.

## TL;DR

| Question | Answer |
|---|---|
| Do I need to set anything? | No. Every command runs with no variable set. |
| Which variable do I set most? | `PLOTWORK_CONFIG`, to name a settings file, and `PLOTWORK_ORG` with `PLOTWORK_API_KEY` to check against an organisation's saved rules. |
| Is a key ever printed? | No. `PLOTWORK_API_KEY` is sent only to read the rules and never appears in the output or a report. |
| Do `PLOTWORK_USAGE` and `DO_NOT_TRACK` matter? | Not here. The command line counts nothing and sends nothing whatever they say. They control the local MCP server. |

## The variables it reads

| Variable | Read by | What it does |
|---|---|---|
| `PLOTWORK_CONFIG` | `sync`, `validate`, `check`, `render`, `outline`, `generate`, `publish` | The settings file to read when `--config` is not given, instead of looking for `plotwork.config.json` or `.plotwork/config.json`. |
| `PLOTWORK_ORG` | `check` | The organisation whose saved style rules to check against when `--org` is not given. |
| `PLOTWORK_API_KEY` | `check`, `publish` | An API key: for `check`, of the organisation whose rules are read; for `publish`, the key the diagrams are saved with. Never printed. |
| `PLOTWORK_API_URL` | `check`, `publish` | The API the rules are read from and diagrams are published to, instead of `https://api.plotwork.dev`. |
| `PLOTWORK_VENDOR_ICONS` | `sync`, `render`, `export`, `generate` | `off` draws no vendor artwork in this run: a product icon becomes a plain shape. |
| `GITHUB_REPOSITORY`, `GITHUB_SHA`, `GITHUB_REF`, `GITHUB_RUN_ID`, `GITHUB_SERVER_URL`, `GITHUB_EVENT_NAME` | `generate` | Read only to name the run in a `json` report, when GitHub Actions sets them. |

## The variables it ignores

| Variable | Why |
|---|---|
| `PLOTWORK_USAGE` | Turns on the local MCP server's opt-in usage counts. The command line keeps no counts, so there is nothing to turn on. See [Usage counts and sharing](https://docs.plotwork.dev/mcp/usage.md). |
| `DO_NOT_TRACK` | Stops the local MCP server sharing its totals. The command line shares nothing. |
| `PLOTWORK_API_URL` outside `check` | Only `check --org` talks to the API. `read` fetches a hosted link from the address you give it. |
| `NO_COLOR`, `FORCE_COLOR` | The output has no colour to turn off. |

## Set them in CI

Put a key in your CI system's secret store and pass it to the one step that needs it:

```yaml
- run: npx -y @buun_group/plotwork@0.1.0 check --org acme --format github "**/*.md"
  env:
    PLOTWORK_API_KEY: ${{ secrets.PLOTWORK_API_KEY }}
```

Use an API key of the organisation, created in the organisation's keys in the [portal](https://app.plotwork.dev), so the check keeps working when the person who set it up leaves. Saving rules in an organisation is part of Pro; see [Repository settings](https://docs.plotwork.dev/repository-settings.md).

## See also

| Doc | Why |
|---|---|
| [Configuration](https://docs.plotwork.dev/cli/configuration.md) | How the settings file is found |
| [Repository settings](https://docs.plotwork.dev/repository-settings.md) | Sharing rules across repositories with an organisation |
| [Privacy policy](https://docs.plotwork.dev/privacy-policy.md) | What Plotwork keeps, and what it never receives |