> 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/basic-cli-commands.md). # Basic CLI Commands The commands in `@govplane/cli`. All of them read; none of them writes a policy document. ## `govplane validate` Validates a draft or bundle against the same rules the control plane applies. **The file is never modified**, and every detectable problem is reported in one pass. ```bash govplane validate # the default draft and bundle govplane validate ./policy-bundle.json # an explicit file govplane validate ./policies.json --type bundle govplane validate --strict --format json ``` | Option | Purpose | | ------------------------------ | ------------------------------------------ | | `--type ` | Force the document type; `auto` detects it | | `--strict` | Treat warnings as errors | ``` ✓ governance/policy-bundle.json is valid Type: bundle Policies: 1 Rules: 1 Schema: 1 ``` A failure names the field, explains it, and gives a stable error code: ``` Validation failed: governance/policy-bundle.json 1 error found: 1. policies[0].rules[0].effect Effect type "mutate" is not recognised. INVALID_RULE_EFFECT ``` Error codes are part of the stable contract and match the SDK's — see [Policy Bundle Schema](/docs/documentation/schemas/policy-bundle.md). ## `govplane inspect` A human-readable summary of a document. ```bash govplane inspect # summary govplane inspect --policies # policy listing govplane inspect --policy # one policy in detail govplane inspect --targets # every covered target govplane inspect --context # context fields the policies reference govplane inspect --signature # signature metadata and verification ``` ``` Govplane Policy Bundle Bundle: Schema: 1 Environment: prod Generated at: 2026-08-08T15:19:34.479Z Bundle version: 4 Contents: Policies: 1 Active policies: 1 Rules: 1 Integrity: Checksum: sha256:b65a57ea… Status: matches canonical payload ``` ``` Policies KEY TARGET RULES STATUS auth-login-authenticate auth / login / authenticate 1 active ``` `--context` is the quickest way to answer "what does my application actually have to pass in?" before wiring up the SDK. ### Verifying a signature ```bash govplane inspect --signature --public-key ./keys/prod.pem ``` The key can also come from configuration (`signature.publicKeyPath`) or from `GOVPLANE_PUBLIC_KEY` / `GOVPLANE_PUBLIC_KEY_PATH`. A failed verification exits `4`. ## `govplane working-folder` ```bash govplane working-folder # show the resolved folder govplane working-folder --verbose # and where it came from govplane working-folder set ./governance # persist a default govplane working-folder set ./gov --create # create it first govplane working-folder reset # forget the persisted default govplane working-folder init # scaffold Govplane files govplane working-folder init --force # replace existing generated files ``` `set` and `reset` are the only commands that write to your user-level configuration (`~/.govplane/config.json`). ## `govplane version` ```bash govplane version govplane version --verbose # + Node.js, platform, install path govplane version --check # ask npm for a newer release govplane version --format json ``` `--check` is **the only network access in the basic CLI**, and only with the flag. It exits `0` even when the registry cannot be reached — a version check is not a reason to fail a build. ## `govplane help` ```bash govplane help govplane help govplane --help ``` `govplane help` lists toolkit commands too, marked as requiring the CLI Toolkit, so you can discover them before installing anything. ## Global options Accepted by every command that can make use of them: ``` -w, --working-folder Directory Govplane reads and writes project files in --config Configuration file to use --format Output format --quiet Suppress non-essential output --verbose Additional diagnostic information -h, --help Command help -v, --version CLI version ``` `--quiet` silences noise, not results: errors still go to stderr and `--format json` still prints. `--verbose` never includes tokens, licence keys, private signing keys or secret environment variables. ## Exit codes ```bash govplane validate --format json || echo "failed with $?" ``` | Code | Meaning | | ---- | -------------------------------------------------------------------------------------------- | | `0` | Success | | `1` | The operation failed — validation errors, unparsable document, policy not found | | `2` | File or working-folder error | | `3` | Invalid CLI arguments | | `4` | Compatibility failure — unsupported schema, unsupported Node.js, or a failed signature check | | `5` | Unexpected internal error | | `7` | CLI Toolkit unavailable or inactive | Code `4` is command-scoped: on `validate` it means an unsupported schema; on `inspect` it means signature verification failed. ## Next * [Configuring the CLI](/docs/documentation/cli/configuring-the-cli.md) * [CLI Toolkit Commands](/docs/documentation/cli/cli-toolkit-commands.md) ## More detail Full per-command reference, including every flag and every exit condition: * [`validate`](https://github.com/Govplane/govplane-cli/blob/main/docs/commands/validate.md) · [`inspect`](https://github.com/Govplane/govplane-cli/blob/main/docs/commands/inspect.md) · [`version`](https://github.com/Govplane/govplane-cli/blob/main/docs/commands/version.md) · [`help`](https://github.com/Govplane/govplane-cli/blob/main/docs/commands/help.md) · [`working-folder`](https://github.com/Govplane/govplane-cli/blob/main/docs/commands/working-folder.md) * [Exit codes, per command](https://github.com/Govplane/govplane-cli/blob/main/docs/exit-codes.md) * [Document model](https://github.com/Govplane/govplane-cli/blob/main/docs/document-model.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/basic-cli-commands.md?ask=&goal= ``` `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.