CLI reference

ctxgrd 0.46.0 – the complete public surface: commands, flags, exit codes, output formats, and rule codes.

Exit-code contract

The same contract applies to every command and every --format value.

Code	Meaning
`0`	Clean – no diagnostics, no errors.
`1`	Diagnostics present (lint violations, drift detected, done-gate not met).
`2`	Config or kernel error – `ctxgrd.toml` unreadable, malformed, or a dependency cycle.

Scripts and agents branch on exit code; they do not need to parse text output. stdout is always a clean, parseable stream. Progress notes and hints go to stderr.

Global flags

These flags apply before any subcommand and to the default lint command when invoked bare.

Flag	Default	Description
`--root <PATH>`	`.`	Project root – the directory that contains `ctxgrd.toml`.
`--format <FORMAT>`	`rich`	Output format for `lint`. Values: `rich`, `simple`, `json`.
`--harness <HARNESS>`	–	Emit a turn-end decision for the named agent harness. Only valid value: `claude`. Incompatible with `--recursive`.
`-r`, `--recursive`	off	Lint every `ctxgrd.toml` found under `--root`, each as its own project.
`-V`, `--version`	–	Print version and exit.

Commands

`lint` (default)

Lint the document tree against ctxgrd.toml. Invoked when no subcommand is given.

ctxgrd lint
ctxgrd lint --format json
ctxgrd --root /path/to/repo lint --format json
ctxgrd -r                           # monorepo: lint all ctxgrd.toml files

Formats

Value	Description
`rich`	Column-aligned human table with coloured severity markers (default).
`simple`	Plain text, one diagnostic per line – suitable for `grep`.
`json`	`{"exit_code": N, "diagnostics": [...], "kernel_messages": [...]}` – stable schema.

The --harness claude flag selects the Claude Code Stop-hook format (ADR-062) instead of a --format value; see ctxgrd hooks claude for wiring details.

Exit codes: standard contract (0 / 1 / 2).

`status`

Report the project’s pipeline position: the resolved namespace DAG, per-stage verdicts, open-BUG blockers, and a next-action hint.

ctxgrd status
ctxgrd status --format json
ctxgrd status --lineage PRD-3 --exit-code
ctxgrd status --format mermaid

Flag	Description
`--format <FORMAT>`	`text` (default), `json`, `mermaid`, `dot`.
`--lineage <ID>`	Scope to one feature: the transitive dependents of `<ID>` plus `<ID>` itself.
`--exit-code`	Project the done-signal onto the process exit: `0` when frontier is empty and no blockers, `1` otherwise. Report is still printed; no file is modified.

The mermaid and dot formats emit DAG diagram source only; they do not render an image.

Exit codes: 0 clean; 1 diagnostics or feature not done (when --exit-code); 2 config error or dependency cycle.

See Polling a feature done-signal in an agent loop for agent-loop patterns.

`rules`

Introspect the resolved rule set for the current ctxgrd.toml.

ctxgrd rules
ctxgrd rules --format json
ctxgrd rules --namespace ADR
ctxgrd rules core.cross-ref         # detail view for one rule

Flag	Description
`--namespace <NS>`	Filter output to one namespace.
`--format <FORMAT>`	`rich` (default), `simple`, `json`. `json` includes full descriptions.
`[RULE_CODE]`	Optional positional: print a detail block for one rule code.

Exit codes: standard contract.

`pack`

Inspect and apply rule packs – reusable namespace bundles.

ctxgrd pack list
ctxgrd pack show <name>
ctxgrd pack add <name>
ctxgrd pack outdated
ctxgrd pack migrate
ctxgrd pack migrate --dry-run
ctxgrd pack migrate --dry-run --format json

Subcommand	Exit on clean	Exit on action needed
`list`	`0`	–
`show <name>`	`0`	`2` (unknown pack)
`add <name>`	`0`	`2` (unknown pack or config error)
`outdated`	`0` (all current)	`1` (drift present)
`migrate`	`0` (no dirty blocks remain)	`1` (dirty blocks left for manual resolution)

pack add appends pack blocks to ctxgrd.toml with a provenance comment (# pack: <name>@<version> sha:<fingerprint>). It never clobbers an existing namespace block.

See Keeping adopted packs current for migration workflows.

`init`

Write a starter ctxgrd.toml.

ctxgrd init
ctxgrd init --namespaces ADR,PRD,SPEC
ctxgrd init --pack project-docs
ctxgrd init --stdout                # print to stdout, do not write a file
ctxgrd init --force                 # overwrite an existing ctxgrd.toml

Flag	Description
`--namespaces <LIST>`	Comma-separated namespace names. Default: `ADR`.
`--pack <NAME>`	Apply one or more packs after writing the base config. Repeatable.
`--stdout`	Print to stdout instead of writing the file.
`--force`	Overwrite an existing `ctxgrd.toml`.

Exit codes: 0 on success; 2 if ctxgrd.toml already exists and --force is absent.

`new`

Scaffold a new document, or a new external rule script.

ctxgrd new ADR "Adopt PostgreSQL"
ctxgrd new PRD "Billing overhaul" --id 12
ctxgrd new rule design.token-check "token references must resolve"
ctxgrd new ADR "Use Redis" --stdout    # print to stdout, do not write a file

Argument / flag	Description
`<NAMESPACE>`	Namespace (e.g. `ADR`, `PRD`), or the literal `rule` to scaffold an external rule.
`<TITLE>`	Document title, or rule code like `design.foo` when namespace is `rule`.
`[DESCRIPTION]`	One-line rule description – only used when namespace is `rule`.
`--id <N>`	Explicit document number. Default: `max(existing) + 1`.
`--out <DIR>`	Target directory override.
`--stdout`	Print scaffolded content to stdout.

Exit codes: 0 on success; 2 on config error or unknown namespace.

`hooks`

Manage git hooks that gate commits on ctxgrd.

ctxgrd hooks install
ctxgrd hooks claude

Subcommand	Description
`install`	Install a pre-commit hook that runs `ctxgrd lint` before each commit.
`claude`	Print the Claude Code Stop-hook wiring and detect whether it is already installed. Print-and-detect only – never writes `settings.json`.

Exit codes: 0 on success; 2 on config error.

`refs`

List every location pointing at a document ID: the document itself (if file-backed), depends_on references from other documents, body cross-ref tokens, and reference-scanner hits.

ctxgrd refs ADR-001
ctxgrd refs PRD-12 --format json

Flag	Description
`--format <FORMAT>`	`rich` (default), `simple` (one `<file>:<line>:<col>` per line), `json`.

Output is deterministic so callers can diff across runs.

Exit codes: standard contract.

`list`

List ingested documents grouped by namespace.

ctxgrd list
ctxgrd list --namespace ADR
ctxgrd list --format json
ctxgrd list --format markdown

Flag	Description
`--namespace <NS>`	Filter to one namespace.
`--format <FORMAT>`	`rich` (default), `markdown` (H2 + pipe table per namespace), `json`.

Exit codes: standard contract.

`pin`

Manage commit pins on documents (see ../namespaces.md for pin configuration).

ctxgrd pin --bless ADR-001
ctxgrd pin --bless ADR-001 --force

Flag	Description
`--bless <ID>`	Re-pin the named document’s `pin.commit` to the current HEAD.
`--force`	Bless even when scoped paths have uncommitted changes.

Exit codes: 0 on success; 2 on config error or when uncommitted changes are present without --force.

`lsp`

Start the Language Server Protocol server over stdio.

ctxgrd lsp

The LSP server streams diagnostics to editors as documents change. See ../editors.md for editor integration.

Exit codes: 0 on clean shutdown; 2 on startup error.

`docs`

Print an end-user guide bundled with the binary.

ctxgrd docs rules
ctxgrd docs namespaces
ctxgrd docs sources
ctxgrd docs packs

Rule inventory

Rules are identified by <prefix>.<name>. The prefix groups rules by origin.

`core.*` – built-in structural rules

These rules are always available and applied to any namespace that enables them in ctxgrd.toml.

Code	Summary
`core.frontmatter`	Documents must contain parseable YAML frontmatter.
`core.id`	Documents must declare a valid ID.
`core.id-unique`	Document numbers must be unique per namespace.
`core.required-headings`	Required H2 headings must be present.
`core.required-metadata`	Required metadata keys must be present and non-empty.
`core.allowed-values`	Metadata values must match configured allow-lists.
`core.dep-resolved`	`depends_on` references must point to existing documents.
`core.dep-cycle`	Dependency graphs must be acyclic.
`core.cross-ref`	Cross-reference tokens in the document body must resolve.
`core.min-docs`	Seeded namespaces must hold at least one document.
`core.requires-link`	This file must reference each configured target file.
`core.acceptance-complete`	Terminal-status documents must have no unchecked acceptance-criteria boxes.

core.acceptance-complete is opt-in – it fires only when enabled in ctxgrd.toml. See Polling a feature done-signal in an agent loop for configuration.

Pack rules

These rules are provided by packs and applied only to namespaces the pack defines.

Code	Pack	Summary
`agents.context-budget`	claude	Instruction-file imports resolve and the body stays within budget.
`agents.context-cache`	claude	Commit-context cache signals for instruction files.
`agents.context-headings`	claude	Instruction files stay free of volatile state and link TODO.md lazily.
`agent.frontmatter`	claude	Claude Code subagent files have a well-formed `name`/`description`.
`agent.assigned`	workflow	Every agent a TASK assigns resolves to a file agent or a configured built-in.
`ears.clause-syntax`	workflow	EARS-id’d requirements clauses parse as one of the six EARS patterns.
`guide.frontmatter`	guide	End-user guides have a non-empty `title` and a valid Diátaxis `type`.
`design.section-order`	design	DESIGN.md H2 sections must follow canonical order.
`design.token-ref`	design	DESIGN.md `{token.ref}` references must resolve.
`todo.freshness`	project-docs	TODO.md carries a freshness line and is not stale.
`todo.structure`	project-docs	TODO.md has a checklist and a context section.

Run ctxgrd rules for the full list resolved against your ctxgrd.toml, including any external rules defined in rules/.

Output format notes

`--format json` (lint)

{
  "exit_code": 0 | 1 | 2,
  "diagnostics": [
    {
      "code": "<rule-code>",
      "file": "<path>",
      "line": <N>,
      "severity": "error" | "warning",
      "message": "<text>"
    }
  ],
  "kernel_messages": ["<text>"]
}

stdout is a single JSON object. The exit code embedded in the object matches the process exit code.

`--format json` (`--recursive`)

{
  "recursive": true,
  "exit_code": 0 | 1 | 2,
  "roots": [
    { "root": "<path>", "exit_code": N, "diagnostics": [...], "kernel_messages": [...] }
  ]
}

`status --format json`

Follows the SPEC-002 data model. Key top-level fields: stages, frontier, next_action, blockers. Each stage includes namespace, state (done / current / pending / blocked), verdict, and shared. Pipe to jq or any JSON processor – stdout is a clean stream.

Configuration

ctxgrd reads ctxgrd.toml from --root. Run ctxgrd init to create one. See ../namespaces.md for the full config schema and ../packs.md for pack adoption.

CLI reference

Exit-code contract

Global flags

Commands

lint (default)

status

rules

pack

init

new

hooks

refs

list

pin

lsp

docs

Rule inventory

core.* – built-in structural rules

Pack rules

Output format notes

--format json (lint)

--format json (--recursive)

status --format json

Configuration

`lint` (default)

`status`

`rules`

`pack`

`init`

`new`

`hooks`

`refs`

`list`

`pin`

`lsp`

`docs`

`core.*` – built-in structural rules

`--format json` (lint)

`--format json` (`--recursive`)

`status --format json`