Plugins · CCPP PQL

The ccpp pql command

ccpp pql compiles, checks and formats PQL programs and shows what the compiler knows: functions, policies, registry, diagnostics.

The prompt box and the terminal run the same compiler. Every command prints Markdown, or JSON with --json. A program is a file, or standard input when there is no file or the file is -; a leading $ is accepted.

Command	Purpose
`ccpp pql compile [file]`	Compile a program into the prompt Claude reads.
`ccpp pql check [file]`	Diagnostics only.
`ccpp pql fmt [file]`	Print the normalized program (`--check`: exit 1 when not formatted).
`ccpp pql functions [list]`	The function definitions of the project and user layers, with their status.
`ccpp pql functions show ID`	Signature, file, `claudeCanEdit`, parameters and source of a definition.
`ccpp pql functions lint`	Validate every definition; exit 1 on an error.
`ccpp pql catalog`	What the prompt box completes from: functions and CPO policies.
`ccpp pql registry`	Keywords by role, HOW directives with their forms and strength, identifier domains.
`ccpp pql diagnostics`	Every diagnostic code with its severity and summary.

compile, check, functions and catalog take --cwd DIR, the project root where .claude/pql/ is read (the current directory by default). User definitions are read from ~/.ccpp/pql/ ($CCPP_HOME/pql/).

compile

ccpp pql compile program.pql             # the prompt, then the diagnostics
ccpp pql compile --prompt < program.pql  # the prompt alone; diagnostics on stderr
ccpp pql compile program.pql --json      # the JSON the prompt box reads

The exit code is 1 when the program has an error, and no partial prompt is printed. Diagnostics read as a position, a code, a severity and a message; lines and columns are 1-based and count from after the $:

- `2:7` `PQL-S002` error: Unterminated string: a string closes with `"` on the same line.

A diagnostic raised inside a function definition points into its file and lists the calls that produced it (via #a, #b). --json prints ok, prompt, normalized, diagnostics (with start and end positions) and manifest.

check, fmt

check exits 1 on errors ({ "ok", "diagnostics" } with --json). fmt refuses a program with syntax errors.

ccpp pql check plan.pql && ccpp pql fmt --check plan.pql

functions

ccpp pql functions shows each definition with its status (active, disabled, overridden, invalid), kind, layer and signature. ccpp doctor reports invalid definitions as the check pql: function definitions.

Programs in files

A .pql file you keep in the repository can be reviewed like code and compiled in CI:

ccpp pql check --cwd . plans/release.pql

Paste it in the prompt box after a $, or compile it and give Claude the prompt, to run it.