229 lines
8.2 KiB
Markdown
229 lines
8.2 KiB
Markdown
# CLI Reference
|
|
|
|
This is the canonical reference for the implemented Notarius command-line
|
|
interface.
|
|
|
|
For the minimal end-to-end invocation, see the [README](../README.md).
|
|
|
|
## Commands
|
|
|
|
```text
|
|
notarius help
|
|
notarius run <pipeline-id> --input path/to/source.json [--config path/to/config.yml] [--only lane-a,lane-b] [--chunk_cache auto|bypass|refresh] [--output-dir path] [--resume] [--debug [--debug-dir path]] [--llm-profile id] [--session-id id] [--reference selector=path] [--without-reference selector]
|
|
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` with no arguments, `notarius help`, `notarius --help`, or
|
|
`notarius -h` prints usage and exits successfully.
|
|
|
|
## `run`
|
|
|
|
`notarius run <pipeline-id>` executes a configured pipeline against one input
|
|
file.
|
|
|
|
Flags:
|
|
|
|
- `--input path`: required source input file.
|
|
- `--config path`: config file path. If omitted, Notarius uses the discovery
|
|
rules in [Configuration](config.md#discovery).
|
|
- `--only lane-a,lane-b`: run only the named artifact lanes. Values are
|
|
comma-separated and must be non-empty.
|
|
- `--resume`: request checkpoint reuse for this invocation. See
|
|
[Operations](operations.md#checkpoint-cache) for prerequisites and reuse
|
|
behavior.
|
|
- `--chunk_cache auto|bypass|refresh`: select chunk-plan reuse for this
|
|
invocation. `auto` reuses a valid plan by canonical source digest, `bypass`
|
|
performs no plan-cache I/O, and `refresh` regenerates and replaces a valid
|
|
plan only after chunk validation succeeds. See
|
|
[Configuration](config.md#state-surfaces) for the persistent setting, precedence,
|
|
and cache-root selection.
|
|
- `--output-dir path`: output root. Defaults to `./notarius-output`.
|
|
- `--debug`: allocate and retain one debug bundle for this invocation.
|
|
- `--debug-dir path`: debug-bundle root override. This flag requires `--debug`.
|
|
- `--llm-profile id`: override every effective LLM-capable pipeline module
|
|
binding with one Scriptorium profile ID. Validator-specific profiles are not
|
|
overridden.
|
|
- `--session-id id`: pass a stable prompt session identifier through LLM-backed
|
|
module calls.
|
|
- `--reference selector=path`: bind a reference path to a chunk, extractor,
|
|
merger, or normalizer reference slot. Repeatable.
|
|
- `--without-reference selector`: remove a configured optional reference binding.
|
|
Repeatable. It accepts the same selector forms as `--reference`, without
|
|
`=path`.
|
|
|
|
On success, the command prints the completed pipeline ID, normalized output and
|
|
rejected output counts, and the output directory. A debug-enabled run also
|
|
prints `debug=<bundle-path>`. If the run completes with warnings, the warning
|
|
count is printed to stderr.
|
|
|
|
Reference flags are resolved against selected chunk, extractor, merger, and
|
|
normalizer targets before the run starts. Flat slot names are accepted only
|
|
when exactly one selected target declares that slot. For configured reference
|
|
bindings, precedence, path resolution, and validation, see
|
|
[Configuration](config.md#pipelines).
|
|
|
|
`--reference` binds or replaces one slot for one selected target. Selectors are:
|
|
|
|
- `slot=path`: valid when exactly one selected target declares `slot`;
|
|
- `chunk.slot=path`: target the chunker;
|
|
- `merge.slot=path`: valid when exactly one selected merger declares `slot`;
|
|
- `lane.slot=path`: valid when exactly one selected extractor, merger, or
|
|
normalizer in that lane declares `slot`;
|
|
- `lane.extract.slot=path`: target a lane extractor;
|
|
- `lane.merge.slot=path`: target a lane merger;
|
|
- `lane.normalize.slot=path`: target a lane normalizer.
|
|
|
|
Use `slot=path` when the selected targets declare the slot unambiguously:
|
|
|
|
```sh
|
|
go run ./cmd/notarius run dnd-session \
|
|
--config examples/dnd-spells.config.yml \
|
|
--input examples/seriatim-minimal-transcript.json \
|
|
--reference roster=./campaign-roster.txt
|
|
```
|
|
|
|
Use an explicit selector when multiple selected targets declare the same slot or
|
|
when you want to target a specific target:
|
|
|
|
```sh
|
|
go run ./cmd/notarius run dnd-session \
|
|
--config examples/dnd-spells.config.yml \
|
|
--input examples/seriatim-minimal-transcript.json \
|
|
--reference spells.extract.glossary=./campaign-glossary.txt
|
|
```
|
|
|
|
The same grammar can target chunk, merge, and normalize slots when the configured
|
|
modules declare them:
|
|
|
|
```sh
|
|
go run ./cmd/notarius run dnd-session \
|
|
--config path/to/config.yml \
|
|
--input examples/seriatim-minimal-transcript.json \
|
|
--reference chunk.scene_guide=./campaign-scenes.txt \
|
|
--reference spells.merge.merge_notes=./merge-notes.txt \
|
|
--reference spells.normalize.normalization_notes=./normalization-notes.txt
|
|
```
|
|
|
|
Use `--without-reference` to remove a configured optional binding for a run:
|
|
|
|
```sh
|
|
go run ./cmd/notarius run dnd-session \
|
|
--config examples/dnd-spells.config.yml \
|
|
--input examples/seriatim-minimal-transcript.json \
|
|
--without-reference glossary
|
|
```
|
|
|
|
Use `--session-id` when an external orchestrator needs all prompt calls from one
|
|
run to share an identifier:
|
|
|
|
```sh
|
|
go run ./cmd/notarius run dnd-session \
|
|
--config examples/dnd-spells.config.yml \
|
|
--input examples/seriatim-minimal-transcript.json \
|
|
--session-id campaign-17-session-04
|
|
```
|
|
|
|
The resume flag can be added to an otherwise identical run invocation. It both
|
|
loads compatible checkpoints and records replacements for work executed by that
|
|
invocation; without it, the checkpoint root is not used:
|
|
|
|
```sh
|
|
go run ./cmd/notarius run dnd-session \
|
|
--config examples/dnd-spells.config.yml \
|
|
--input examples/seriatim-minimal-transcript.json \
|
|
--resume
|
|
```
|
|
|
|
Use `--debug` to retain the redacted summary and trace bundle for one run. The
|
|
bundle is allocated before pipeline resolution; once allocated, its path is
|
|
also printed to stderr if the command fails. Debug-write failures cause exit
|
|
code `1`.
|
|
|
|
```sh
|
|
go run ./cmd/notarius run dnd-session \
|
|
--config examples/dnd-spells.config.yml \
|
|
--input examples/seriatim-minimal-transcript.json \
|
|
--debug --debug-dir ./notarius-debug
|
|
```
|
|
|
|
Use `refresh` when intentionally replacing the cached plan for the same source:
|
|
|
|
```sh
|
|
go run ./cmd/notarius run dnd-session \
|
|
--config examples/dnd-spells.config.yml \
|
|
--input examples/seriatim-minimal-transcript.json \
|
|
--chunk_cache refresh
|
|
```
|
|
|
|
Use `bypass` for a one-off run that must not inspect or create plan-cache state:
|
|
|
|
```sh
|
|
go run ./cmd/notarius run dnd-session \
|
|
--config examples/dnd-spells.config.yml \
|
|
--input examples/seriatim-minimal-transcript.json \
|
|
--chunk_cache bypass
|
|
```
|
|
|
|
`--diagnostics-dir` has been removed. For checkpoint behavior, durable output,
|
|
debug-bundle lifecycle, and failure inspection, see [Operations](operations.md).
|
|
|
|
## `config validate`
|
|
|
|
`notarius config validate` loads and validates configuration.
|
|
|
|
Flags:
|
|
|
|
- `--config path`: config file path. If omitted, Notarius uses the discovery
|
|
rules in [Configuration](config.md#discovery).
|
|
- `--pipeline pipeline-id`: additionally resolve one configured pipeline against
|
|
the production module catalog.
|
|
- `--only lane-a,lane-b`: validate resolution for selected artifact lanes. This
|
|
flag requires `--pipeline`.
|
|
|
|
Examples:
|
|
|
|
```sh
|
|
go run ./cmd/notarius config validate \
|
|
--config examples/dnd-spells.config.yml
|
|
|
|
go run ./cmd/notarius config validate \
|
|
--config examples/dnd-spells.config.yml \
|
|
--pipeline dnd-session \
|
|
--only spells
|
|
```
|
|
|
|
## `pipelines list`
|
|
|
|
`notarius pipelines list` prints configured pipeline IDs in sorted order.
|
|
|
|
Flags:
|
|
|
|
- `--config path`: config file path. If omitted, Notarius uses the discovery
|
|
rules in [Configuration](config.md#discovery).
|
|
- `--json`: print `{"pipelines":[...]}` instead of one ID per line.
|
|
|
|
Examples:
|
|
|
|
```sh
|
|
go run ./cmd/notarius pipelines list \
|
|
--config examples/dnd-spells.config.yml
|
|
|
|
go run ./cmd/notarius pipelines list \
|
|
--config examples/dnd-spells.config.yml \
|
|
--json
|
|
```
|
|
|
|
## Exit Codes
|
|
|
|
- `0`: command succeeded.
|
|
- `1`: command syntax was valid, but loading config, resolving modules, running
|
|
the pipeline, calling the provider, writing output, or writing a requested
|
|
debug bundle failed.
|
|
- `2`: command syntax was invalid, a command was unknown, a required argument
|
|
was missing, or a flag value was malformed.
|
|
|
|
For YAML structure, defaults, Scriptorium profile sources, environment
|
|
overrides, and selectable module and validator keys, see
|
|
[Configuration](config.md).
|