> For the complete documentation index, see [llms.txt](https://govplane.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://govplane.gitbook.io/docs/documentation/cli/configuring-the-cli.md).

# Configuring the CLI

Two files and a handful of environment variables. Neither file is required — the CLI has working defaults for everything.

## The working folder

The directory the CLI reads and writes project files in, resolved in this order:

| Precedence | Source                                                  |
| ---------- | ------------------------------------------------------- |
| 1          | `--working-folder <path>` / `-w <path>`                 |
| 2          | `GOVPLANE_WORKING_FOLDER`                               |
| 3          | Persisted configuration (`govplane working-folder set`) |
| 4          | The current terminal directory                          |

```bash
govplane working-folder --verbose
```

```
Working folder: /Users/example/projects/my-api/governance
Source:         persisted configuration
```

Everything else — the draft, the bundle, the config file, key paths — is resolved **relative to this folder**, which is why one `-w` flag redirects a whole command.

## Project configuration

`govplane.config.json`, in the working folder.

```json
{
  "schemaVersion": 1,
  "draft":     { "path": "policy-drafts.json" },
  "bundle":    { "path": "policy-bundle.json" },
  "signature": { "publicKeyPath": "keys/prod.pem" },
  "limits":    { "maxFileBytes": 8388608 }
}
```

| Field                     | Default              | Purpose                           |
| ------------------------- | -------------------- | --------------------------------- |
| `schemaVersion`           | —                    | Configuration schema version      |
| `draft.path`              | `policy-drafts.json` | Draft document                    |
| `bundle.path`             | `policy-bundle.json` | Runtime bundle                    |
| `signature.publicKeyPath` | —                    | Key used by `inspect --signature` |
| `limits.maxFileBytes`     | `8388608` (8 MiB)    | Maximum document size             |

Paths inside are relative to the working folder:

```json
{ "draft": { "path": "policies/drafts.json" }, "bundle": { "path": "dist/runtime-bundle.json" } }
```

```
<working-folder>/policies/drafts.json
<working-folder>/dist/runtime-bundle.json
```

**Unknown fields are ignored**, so one config file works for both the CLI and the toolkit — the toolkit adds `build`, `sign`, `analyze` and `simulate` blocks the CLI simply skips. See [Configuring the Toolkit](/docs/documentation/cli/configuring-the-cli-toolkit.md).

### A different file

```bash
govplane validate --config ./config/govplane.prod.json
```

Relative `--config` paths resolve from the working folder. A `--config` you name that does not exist is an error (exit `2`); a *missing default* file is not — the CLI just uses its defaults.

## User configuration

`~/.govplane/config.json`, or `$GOVPLANE_HOME/config.json`.

```json
{
  "schemaVersion": 1,
  "workingFolder": "/Users/example/projects/my-api/governance"
}
```

Written only by `govplane working-folder set` and `reset`. If it is missing or unreadable the CLI falls back to defaults rather than failing — persisted settings are a convenience, never a requirement.

## Environment variables

| Variable                   | Purpose                                               |
| -------------------------- | ----------------------------------------------------- |
| `GOVPLANE_WORKING_FOLDER`  | Working folder, overriding persisted configuration    |
| `GOVPLANE_HOME`            | User-level Govplane directory (default `~/.govplane`) |
| `GOVPLANE_PUBLIC_KEY`      | Inline public key for signature verification          |
| `GOVPLANE_PUBLIC_KEY_PATH` | Path to a public key for signature verification       |
| `NO_COLOR`                 | Disable ANSI colour                                   |
| `FORCE_COLOR`              | Force ANSI colour without a TTY                       |

{% hint style="info" %}
`GOVPLANE_HOME` is the one to know for CI. Pointing it inside the workspace keeps all Govplane state — persisted config, and the toolkit's licence and grace clock — out of the build agent's home directory, so runs do not leak into each other.

```yaml
env:
  GOVPLANE_HOME: ${{ github.workspace }}/.govplane
```

{% endhint %}

## Output formats

Every command supports both:

{% tabs %}
{% tab title="Text" %}

```bash
govplane validate --format text     # default, for humans
```

{% endtab %}

{% tab title="JSON" %}

```bash
govplane validate --format json     # for pipelines
```

{% endtab %}
{% endtabs %}

JSON output is a stable contract; text output is not. Parse the JSON, and match on **error codes**, not on message wording.

```bash
govplane inspect --format json | jq '.bundle.checksum'
```

`--quiet` suppresses non-essential output but still prints JSON and still writes errors to stderr. `--verbose` adds the resolved working folder and its source, the config file in use, the documents processed and the detected type — and never prints secrets.

## In CI

```yaml
- run: npm install --global @govplane/cli
- run: govplane validate --strict --format json
  env:
    GOVPLANE_WORKING_FOLDER: ./governance
    GOVPLANE_HOME: ${{ github.workspace }}/.govplane
```

`--strict` turns warnings into failures, which is usually what you want on a pull request and not on a local run.

## Next

* [Basic CLI Commands](/docs/documentation/cli/basic-cli-commands.md)
* [Configuring the Toolkit](/docs/documentation/cli/configuring-the-cli-toolkit.md)

## More detail

* [Configuration reference](https://github.com/Govplane/govplane-cli/blob/main/docs/configuration.md)
* [Working folder reference](https://github.com/Govplane/govplane-cli/blob/main/docs/working-folder.md)
* [Bundle parity — canonical payload, checksums, ordering](https://github.com/Govplane/govplane-cli/blob/main/docs/bundle-parity.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://govplane.gitbook.io/docs/documentation/cli/configuring-the-cli.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.