279 lines
11 KiB
Markdown
279 lines
11 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] [--recompute-step step-id] [--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. This retains its existing behavior for
|
|
implicit single-step pipelines; explicit multi-step pipelines reject it
|
|
rather than inferring dependency closure.
|
|
- `--resume`: request checkpoint reuse for this invocation. Checkpoint recording
|
|
must be enabled in configuration. See
|
|
[Operations](operations.md#checkpoint-cache) for prerequisites and reuse
|
|
behavior.
|
|
- `--recompute-step step-id`: with `--resume` and checkpoint recording enabled,
|
|
force the named ordered step and every transitive dependent lane to execute.
|
|
Compatible required predecessors and unrelated lanes remain reusable. The
|
|
value may identify an explicit step or the implicit single-step ID `default`;
|
|
it cannot be combined with `--only`.
|
|
- `--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 external file bindings resolved against selected chunk,
|
|
extractor, merger, and normalizer targets before the run starts. Generated
|
|
artifact bindings are configured in ordered steps and cannot be introduced by a
|
|
CLI path flag. 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-minimal.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-minimal.config.yml \
|
|
--input examples/seriatim-minimal-transcript.json \
|
|
--reference spells.extract.glossary=./campaign-glossary.txt
|
|
```
|
|
|
|
For the maintained ordered D&D workflow, use the explicit pipeline. The first
|
|
step produces normalized NPC and scene-description artifacts; the second step
|
|
receives the NPC artifact in memory for spell extraction, combat extraction, and
|
|
combat normalization, and receives the required scene-description artifact for
|
|
combat eligibility:
|
|
|
|
```sh
|
|
go run ./cmd/notarius run dnd-session \
|
|
--config examples/dnd-complete.config.yml \
|
|
--input examples/seriatim-minimal-transcript.json \
|
|
--output-dir ./npc-grounded-output
|
|
```
|
|
|
|
The generated NPC content remains contextual grounding, not spell or combat
|
|
evidence. It is represented in manifests and debug summaries by bounded
|
|
identity and producer provenance, not by payload content or a filesystem path.
|
|
The scene-description artifact is control context: combat extraction calls its
|
|
LLM only for an exact `combat` scene match. See the
|
|
[D&D combat-turn artifact contract](integrations/dnd-combat-turn-artifacts.md)
|
|
for the resulting empty-output and warning behavior.
|
|
|
|
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-minimal.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-minimal.config.yml \
|
|
--input examples/seriatim-minimal-transcript.json \
|
|
--session-id campaign-17-session-04
|
|
```
|
|
|
|
When `cache.checkpoints.enabled` is `true`, runs record checkpoints whether or
|
|
not `--resume` is present. Add the resume flag to load and reuse compatible
|
|
recorded work; using it while checkpoint recording is disabled is an error:
|
|
|
|
```sh
|
|
go run ./cmd/notarius run dnd-session \
|
|
--config examples/dnd-minimal.config.yml \
|
|
--input examples/seriatim-minimal-transcript.json \
|
|
--resume
|
|
```
|
|
|
|
To selectively rerun one ordered step and its dependent lanes, use the step ID
|
|
from the configuration. The selected step and dependents are reported as
|
|
`forced_recompute`; reusable predecessors are reported as `reused`:
|
|
|
|
```sh
|
|
go run ./cmd/notarius run dnd-session \
|
|
--config examples/dnd-complete.config.yml \
|
|
--input examples/seriatim-minimal-transcript.json \
|
|
--resume --recompute-step extract-events
|
|
```
|
|
|
|
Checkpoint decisions use these categories: `reused`, `executed`,
|
|
`forced_recompute`, and `dependency_invalidated`. The reason code and bounded
|
|
detail identify the decision without exposing reference content, local paths,
|
|
or secrets. `--recompute-step` requires checkpoint recording and `--resume`;
|
|
unknown step IDs, empty values, and combinations with `--only` are rejected.
|
|
The operator meanings of checkpoint reason codes are maintained in
|
|
[Operations](operations.md#resume-and-selective-recompute).
|
|
|
|
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-minimal.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-minimal.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-minimal.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-minimal.config.yml
|
|
|
|
go run ./cmd/notarius config validate \
|
|
--config examples/dnd-minimal.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-minimal.config.yml
|
|
|
|
go run ./cmd/notarius pipelines list \
|
|
--config examples/dnd-minimal.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).
|