Use the CLI
Environment variables
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. |
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-beta.13 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 (opens in a new tab), 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.
See also
| Doc | Why |
|---|---|
| Configuration | How the settings file is found |
| Repository settings | Sharing rules across repositories with an organisation |
| Privacy policy | What Plotwork keeps, and what it never receives |