# CLI Reference This is the canonical reference for the implemented Notarius command-line interface. For the shortest successful run, see the [README](../README.md). Configuration fields, discovery rules, and selectable module keys are defined in [Configuration](config.md); runtime state and recovery procedures are defined in [Operations](operations.md). ## Command Summary ~~~ notarius help notarius run --input path/to/source.json [--json] [flags] notarius config validate [--config path/to/config.yml] [--pipeline pipeline-id] [--only lane-a,lane-b] notarius pipelines list [--config path/to/config.yml] [--json] ~~~ Running Notarius without arguments, or with **help**, **--help**, or **-h**, writes the command summary to standard output and exits with status 0. ## run ~~~ notarius run --input path/to/source.json [--json] [flags] ~~~ The **run** command executes the named pipeline for one input file. The pipeline ID and **--input** are required. | Flag | Meaning | | --- | --- | | **--config path** | Use this configuration file. When omitted, configuration discovery applies; see [Configuration](config.md). | | **--input path** | Source input file to process. Required. | | **--output-dir path** | Override the configured output root for this run. | | **--json** | Write the successful run-result receipt as JSON to standard output. | | **--chunk_cache auto\|bypass\|refresh** | Override chunk-plan cache handling for this run. | | **--resume** | Reuse compatible recorded checkpoints when checkpoint recording is enabled. | | **--recompute-step step-id** | With **--resume**, recompute the selected ordered step and its dependent lanes. It cannot be combined with **--only**. | | **--debug** | Retain a debug bundle for this run. | | **--debug-dir path** | Override the debug-bundle root. Requires **--debug**. | | **--only lane-a,lane-b** | Run only the selected comma-separated artifact lanes when that selection is valid for the configured pipeline. | | **--llm-profile id** | Highest-precedence configured profile for selected LLM-backed bindings and validators; it replaces binding and [pipeline](config.md#pipelines) defaults. | | **--session-id id** | Override the generated prompt session identifier with a non-empty value for LLM-backed module calls. | | **--reasoning-effort value** | Replace the selected PromptKit profile's reasoning effort for every LLM-backed call in this run. The value must be non-empty and the flag may be specified only once. | | **--clear-reasoning-effort** | Clear reasoning effort inherited from the selected PromptKit profile for every LLM-backed call in this run. | | **--reference selector=path** | Add or replace a file reference binding. Repeatable. | | **--without-reference selector** | Remove a configured optional reference binding. Repeatable. | **--chunk_cache** accepts only **auto**, **bypass**, or **refresh**. **--debug-dir**, **--output-dir**, **--session-id**, and **--reasoning-effort**, and **--recompute-step** reject explicit empty values. **--reasoning-effort** and **--clear-reasoning-effort** are mutually exclusive. When neither is present, reasoning effort comes from the selected PromptKit profile. These controls apply to the shared run client, including retries and LLM-backed validators, and do not modify configuration or profile files. Persistent reasoning settings remain a PromptKit profile concern. **--recompute-step** requires **--resume**; checkpoint requirements and reuse behavior are documented in [Operations](operations.md). Every run uses one effective prompt session. Without **--session-id**, Notarius generates a stable `notarius:v1:` identifier from the trimmed resolved input module key and the input file's exact raw bytes. The same module and bytes therefore produce the same identifier, regardless of pipeline, references, profile, retries, or run settings. An explicit non-empty value replaces that default. Session identifiers are visible to providers; they are non-secret correlation identifiers, not credential storage. See [Operations](operations.md#operational-limits) for privacy and workflow guidance. ### Reference selectors Use **--reference** only for a reference slot declared by the selected configured target. The accepted selector forms are: | Form | Target | | --- | --- | | slot=path | The unique selected target that declares slot. | | chunk.slot=path | The chunker. | | merge.slot=path | The unique selected merger that declares slot. | | lane.slot=path | The unique extractor, merger, or normalizer in lane that declares slot. | | lane.extract.slot=path | The extractor in lane. | | lane.merge.slot=path | The merger in lane. | | lane.normalize.slot=path | The normalizer in lane. | **--without-reference** uses the same selector forms without =path. Slot names, requiredness, and configured bindings are part of the [configuration contract](config.md). ### Run output Without **--json**, standard output contains the completed pipeline ID, counts of normalized and rejected outputs, and the output directory. A debug-enabled run also prints its debug-bundle path to standard output. A successful run with warnings reports the warning count to standard error. The published JSON bundle is defined by the [JSON output contract](integrations/json-output.md). With **--json**, successful standard output is exactly one `notarius.run-result.v1` JSON document followed by a newline, with no human-oriented status or debug-path line. Its fields and compatibility policy are defined by the [run-result contract](integrations/run-result.md). A caller must check for exit status 0 before decoding this output; a failed write can leave incomplete standard-output bytes that are not a result document. Example: ~~~ OPENROUTER_API_KEY=your-api-key \ go run ./cmd/notarius run dnd-session \ --config examples/dnd-minimal.config.yml \ --input examples/seriatim-minimal-transcript.json ~~~ ## config validate ~~~ notarius config validate [--config path/to/config.yml] [--pipeline pipeline-id] [--only lane-a,lane-b] ~~~ This command loads and validates a configuration. With **--pipeline**, it also resolves that pipeline against the production module catalog. **--only** selects lanes during that resolution and requires **--pipeline**. Success is written to standard output as either config "" is valid or config "" is valid for pipeline "". Examples: ~~~ go run ./cmd/notarius config validate \ --config examples/dnd-minimal.config.yml \ --pipeline dnd-session OPENROUTER_API_KEY=validation-placeholder \ go run ./cmd/notarius config validate \ --config examples/dnd-complete.config.yml \ --pipeline dnd-session ~~~ The placeholder in the second command is sufficient only for offline validation; it cannot run a provider-backed pipeline. ## pipelines list ~~~ notarius pipelines list [--config path/to/config.yml] [--json] ~~~ This command lists configured pipeline IDs in sorted order. By default, it writes one ID per line to standard output. **--json** writes an object shaped as {"pipelines":[...]} instead. ~~~ go run ./cmd/notarius pipelines list \ --config examples/dnd-minimal.config.yml ~~~ ## Output Streams And Exit Statuses Successful commands write their primary result to standard output. Warnings and errors are written to standard error. For **run --json**, warnings remain on standard error and standard output is a machine-readable success result only. Syntax and runtime diagnostics remain on standard error. Parse the result only after the process exits with status 0. | Status | Meaning | | --- | --- | | 0 | The command completed successfully, including root help. | | 1 | Command syntax was valid but configuration loading or validation, pipeline resolution or execution, provider use, output, or requested debug handling failed. | | 2 | The command or flag syntax was invalid, including unknown commands, missing required arguments, invalid flag values, or invalid flag combinations. | The root help spellings are the supported help path. Invoking **--help** on **run**, **config validate**, or **pipelines list** is handled by the flag parser as a usage error: it writes an error to standard error and exits with status 2.