147 lines
5.9 KiB
Markdown
147 lines
5.9 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 [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 [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. |
|
|
| **--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** | Override effective LLM-capable module bindings with one configured profile. |
|
|
| **--session-id id** | Supply a non-empty prompt session identifier to LLM-backed module calls. |
|
|
| **--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
|
|
**--recompute-step** reject explicit empty values. **--recompute-step**
|
|
requires **--resume**; checkpoint requirements and reuse behavior are
|
|
documented in [Operations](operations.md).
|
|
|
|
### 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
|
|
|
|
On success, 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
|
|
envelope is defined by the [JSON output contract](integrations/json-output.md).
|
|
|
|
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.
|
|
|
|
| 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.
|