Skip to content

Find the right command

Use this page as a task index. The installed --help is the complete argument reference for your version. Uppercase names below are placeholders for files you have authored; these forms are contextual, not a script to paste as a unit. For complete runnable examples, start with BookRec, expenses, or the quickstart.

The root option --disclosure internal|customer goes before the subcommand (gnd --disclosure customer check …) and sets the disclosure mode for that invocation; GND_DISCLOSURE sets it for a process. It is accepted only at the root.

Models and facts

Command form Result
gnd validate MODEL --format json Structural and semantic model validation
gnd validate MODEL --document DOC Also re-hash an unattended model's source spans over a declared document
gnd validate MODEL --document DOC --require-documents Exit 3 unless every source span of an unattended model was re-hashed; without the flag, unchecked spans are counted in one unattended:spans-unchecked warning
gnd validate MODEL --trace Text report of transition digests and obligations, without evaluating a walk
gnd check MODEL POPULATION --format json Snapshot constraint and derivation findings
gnd check MODEL POPULATION --rule-ids --format json Report version 15: each verdict carries its rule's declared id and remedy when present, else its position and null (rule-check report)
gnd check MODEL POPULATION --baseline BASE --format json Marks each violation new or standing against BASE; exit 1 only for new must-hold violations, while vacuous and undecided rules keep their own exits (how-to)
gnd check MODEL POPULATION --allow-vacuous --format json Exits 0 when vacuous rules are the only shortfall
gnd check MODEL POPULATION --admission --format json The check plus an asserted-occurrence admission partition
gnd check MODEL --populations DIR Batch checking of population files
gnd check MODEL --pre PRE --steps STEPS --post POST --format json Audit of a declared operation walk
gnd check MODEL COMPOSED --composition RECORD --sources DIR Re-derive a composition, then check it with lineage (composition)
gnd verbalize population MODEL POPULATION --format jsonl Deterministic sentences for supplied facts
gnd compose MODEL DIR --out COMPOSED --record RECORD One population from several anchored sources, with a value-free record
gnd diff MODEL_A MODEL_B --populations DIR --format json Bounded comparisons over a shared vocabulary
gnd coverage MODEL --check REPORT --format json Model-element claims and cited evidence; flags select evidence families

Use --anchors PATH --document PATH for snapshot source anchoring; the sidecar format is in the anchor sidecar reference. Check-family reports normally apply declared redaction; --unredacted requests the value-bearing view. The disclosure mode can grant or refuse that request; see what customer mode refuses. validate --trace is a text surface: JSON validation does not add trace fields.

Project generation and change

Command form Result
gnd codegen MODEL --out DIR Derived project files and initial extension structure
gnd conformance MODEL DIR --format json Static integrity, currency, structure and architecture findings
gnd evolve preview MODEL PROPOSAL --workspace ROOT --records DIR --out PREVIEW [--policy additive --populated FT --check-population FILE] [--shape-report] [--previous-include ID=PATH] Immutable proposal preview for review; the additive policy refuses non-additive operations, and admits a constraint on clean data with --check-population; the shape report lists same-shaped fact types
gnd evolve apply MODEL PROPOSAL --preview PREVIEW --workspace ROOT --records DIR [--policy additive --populated FT --check-population FILE] Model publication and linked-project rechecks; repeats the preview's policy and population check
gnd evolve finalize MODEL PENDING --workspace ROOT --records DIR Completion of an interrupted published evolution
gnd discover MODEL POPULATION --out PROPOSAL --report REPORT --actor ID --requested-at 2026-10-24T12:00:00+00:00 Candidate constraints observed in one population, as a reviewable evolve proposal plus a report; --families fact-type opts in to proposing fact types from generic rows; --type-evidence writes their evidence, and --type-evidence-in with --duplicate-judgements or --shape-judgements renders a skill's verdicts (contract)
gnd recovery inventory ROOT --source SRC --tests TESTS --out INVENTORY Bounded static census of explicitly selected roots
gnd recovery verify ROOT REPORT Recheck a recovered-model bundle and source evidence
gnd import rai-orm RAI_MODEL --out DIR Import of the supported RAI ORM input profile and evidence

Model authoring and recovery interpretation are agent/human workflows, not automatic side effects of validation. See evolution and recovery.

Data and documents

Command form Result
gnd synth MODEL --out CORPUS --class all --seed 17 Supported labeled synthetic populations and provenance
gnd measure MODEL --populations CORPUS --format json Per-constraint false-pass, false-fail and undecided rates
gnd measure MODEL --labels MANIFEST --format json The same rates over populations you labelled yourself, or class-mode agreement counts (contract)
gnd export ilp MODEL --labels MANIFEST --target popper --out DIR Background facts, examples and modes for an ILP learner, from a class-mode label manifest; --target is popper, neutral, ilasp or rules (contract)
gnd export ilp MODEL --population POPULATION --target amie --out DIR One unlabelled population's binary fact types as typed triples for a rule miner (contract)
gnd import ilp-rules MODEL CLAUSES --labels MANIFEST --reported-coverage RUN --target popper --out PROPOSAL Learned clauses as induced, advisory guarded constraints, admitted only when GND's coverage equals the learner's; --target is popper, neutral, ilasp, llm or rules (contract)
gnd import mined-rules MODEL RULES --population POPULATION --reported REPORTED --target amie --out PROPOSAL A rule miner's rules as induced, advisory guarded constraints, admitted only when every count equals the miner's and every rule holds (contract)
gnd extract MODEL --out ARTIFACTS [--guidelines] Offline schema/vocabulary bundle for a separate extraction workflow; --guidelines adds a constraint-blind per-fact-type guideline file
gnd verify MODEL POPULATION --artifacts ARTIFACTS --format json Bound extraction-handoff validation followed by checking
gnd verify MODEL POPULATION --no-extraction --format json Explicitly check directly authored, unextracted facts
gnd doccheck MODEL MANIFEST --artifacts ARTIFACTS Validation of a rendered document's obligations
gnd fidelity MODEL --cases CASES --artifacts ARTIFACTS --format json Per-fact-type extraction fidelity over retained cases

Experiments, review, and orchestration

Command form Result
gnd exp init EXP-001-example --out DIR --kind data-driven --question Q1=TEXT New experiment spec with a named question
gnd exp validate EXPERIMENT Structural validation of its spec
gnd exp author-expectation ... Author and bind an exact expected output; see command help before use
gnd exp run EXPERIMENT --adapter codex A legacy-adapter session under the authored contract
gnd exp run EXPERIMENT --adapter-policy POLICY A declared-policy session under the authored contract
gnd exp close EXPERIMENT Completeness gate for questions/evidence and kind-specific obligations
gnd judgments check MODEL POPULATION --policy POLICY --receipts RECEIPTS --trusted-root ROOT --format json Evaluate saved external opinions and evidence floors
gnd review panel ... / gnd review panel-light ... Explicit advisory reviewer run; inspect help for the selected artifact kind
gnd review finalize ... Validate and render a supplied synthesis against retained reviewer evidence
gnd solve MODEL --workspace DIR ... Gated selected CLI station sequence and walk log

A session adapter may invoke a configured external tool or provider. Those prerequisites and credentials are separate from deterministic tutorial runs.

Proofs, exports, and skill installation

Command form Result
gnd witness MODEL POPULATION --targets REQUEST Redacted finite-witness result (raw under internal)
gnd witness MODEL POPULATION --targets REQUEST --raw --out CERTIFICATE Explicit new raw certificate; refused under customer
gnd replay MODEL POPULATION CERTIFICATE --json Independent finite inference replay
gnd witness ... --composition RECORD / gnd replay ... --composition RECORD Version-2 witness of a composed population, traced to its sources (composition)
gnd witness-view CERTIFICATE --json Non-replayable presentation of a certificate
gnd why-not MODEL POPULATION --fact-type ID Where each clause of a derivation stops, values redacted (raw under internal)
gnd why-not MODEL POPULATION --fact-type ID --row REQUEST Where a derivation stops for one claimed row, with values spelled differently counted; values redacted
gnd export souffle ... / gnd export lean ... / gnd export pyrel ... Selected bounded export profile
gnd install --project Copy packaged skills to project discovery roots
gnd doctor --project Diagnose installed skills and shadowing across scopes
gnd install --sync Refresh standard roots with existing installation receipts
gnd uninstall --project Remove managed skills while preserving user edits

Interpret exits in the command's context

Snapshot check and verify bands are 0 pass, 1 alethic failure, 2 vacuous, 3 invalid input, and 4 indeterminate. A witness band 2 instead means missing, unknown, or unsupported targets. A why-not band 0 means an answer (blocked or derived), 2 an unsupported rule and 4 an unavailable term or a work limit. A session band 15 means nonacceptance; conformance band 13 means drift; closure band 14 means incomplete obligations; solve band 17 means a halted walk.

General command refusals may use 64 for usage, 66 for missing inputs, 70 for internal faults, or 74 for I/O. Consult the command report/help rather than assigning one universal meaning to every nonzero exit. A request for values refused by the disclosure mode exits 3 with nothing on stdout. A misspelled or repeated --disclosure is a usage error, 64.

The authoritative parser lives in cli.py. CLI composition does not enlarge the stable Python API, whose function list is the one count of record.

Shared-vocabulary models use the canonical model includes contract. gnd verbalize model MODEL reads the composed model and identifies its includes. For an edition update, see the expense walkthrough and the evolution contract linked above; --previous-include ID=PATH supplies verified historical bytes when the old edition is unavailable.