176 lines
8.1 KiB
Markdown
176 lines
8.1 KiB
Markdown
# 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 <pipeline-id> --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 <pipeline-id> --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 "<path>" is valid or
|
|
config "<path>" is valid for pipeline "<pipeline-id>".
|
|
|
|
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.
|