# CLI Reference This is the canonical reference for Notarius invocation, command inputs, reports, and outcome codes. [Configuration](config.md) owns fields, defaults, resource selection, and module keys; [Operations](operations.md) owns runtime state; integration contracts own domain payloads. Notarius uses native CommandKit commands with ckconfig and ckprompt. The [upstream CLI reference][native-cli] owns their general parser, report, inspection, and smoke semantics. The examples below show Notarius-specific selections. Use help for every installed command's current options. ## Command Summary ~~~text notarius --help notarius help pipeline run notarius version notarius completion bash notarius pipeline list notarius pipeline show PIPELINE_ID notarius pipeline validate PIPELINE_ID notarius pipeline run PIPELINE_ID --input-file PATH notarius run PIPELINE_ID --input-file PATH notarius config scopes notarius config validate notarius config show notarius config sources notarius config explain notarius config diff notarius promptkit list prompts notarius promptkit show profile PROFILE_ID notarius promptkit requirements show PROMPT_ID notarius promptkit requirements validate PROMPT_ID notarius promptkit show prepared PROMPT_ID notarius promptkit test KIND ~~~ Bare invocation, `help`, `--help`, and `-h` display native help. Help also works on subcommands without their execution-only required inputs. Help, version, and Bash/Zsh/Fish completion need no configuration, credentials, or run storage. `version` reports the application identity; `version --scope commandkit` selects the library identity. Source-tagged installation and release-linked build identity remain available; an unversioned checkout reports `development`. Version output uses native report formats, not a custom root flag. ## Syntax And Supplied Values Put flags after the **complete command path**, optionally interspersed with its operands. Value flags accept `--name value` or `--name=value`. Boolean flags accept presence and explicit values such as `--debug=false`. `--` ends option parsing; later tokens are operands. Singleton flags may repeat; the last successfully parsed occurrence supplies the value. Every occurrence is parsed, so a malformed earlier value remains an error. Repeatable flags retain occurrence order and do not split commas. Omission differs from supplied empty, false, and zero. Semantic validity still depends on the selected command and native request. See [registered syntax][syntax] for the shared rules. ## Configuration Selection `--config PATH` fixes the main source; explicit empty fails instead of discovering another file. Omission uses [configuration discovery](config.md#configuration-discovery-and-precedence). Commands that support `--overlay NAME` select the native application overlay. Configuration and pipeline commands also expose repeated `--set POINTER=JSON`: ~~~sh notarius config show --config examples/dnd-minimal/config.yml \ --set /concurrency/workers=1 --path /concurrency/workers --format json ~~~ The value is JSON, so strings require JSON quoting. Preserve shell quoting: ~~~sh notarius pipeline validate dnd-session \ --config examples/dnd-minimal/config.yml \ --set '/pipelines/dnd-session/mode="permissive"' \ --set /pipelines/dnd-session/max_additional_turns=0 ~~~ Assignments use non-root mapping paths, not sequence indexes. To change a record inside a steps/resource list, use an appropriate source/overlay or replace the complete list. Duplicate or overlapping assignments fail. Version and inheritance controls are not assignment targets. Overrides follow native loading and recorded resolution; they are not an alternate YAML parser. PromptKit commands expose their own native selection/request flags; use help rather than assuming every configuration flag applies to them. ## Pipeline Commands `pipeline list` lists configured IDs in sorted order without module resolution or engine construction. `pipeline show PIPELINE_ID` resolves modules, controls, validator chains, static prompt dependencies, steps/lanes, and reference bindings, without expanding every LLM profile or reading input/reference content. `pipeline validate PIPELINE_ID` performs offline domain resolution and known prompt/profile dependency checks using the shared load and engine when needed. It requires no input transcript, reference file bytes, credential values, provider call, or output/cache/debug directories. Partial profiles remain valid. This is distinct from native configuration validation: request preparation and dynamic selections are checked when used. Show and validate accept configuration selection and native report controls. They inspect the complete configured pipeline; lane selection belongs to run: ~~~sh notarius pipeline list --config examples/dnd-complete/config.yml --format json notarius pipeline show dnd-session --config examples/dnd-complete/config.yml notarius pipeline validate dnd-session --config examples/dnd-complete/config.yml ~~~ ### Run ~~~text notarius run PIPELINE_ID --input-file PATH [flags] notarius pipeline run PIPELINE_ID --input-file PATH [flags] ~~~ `run` is a native alias for `pipeline run`: both resolve to the same declaration and handler. One pipeline ID and a nonempty `--input-file` are required. | Run flag | Meaning | | --- | --- | | `--config PATH`, `--overlay NAME`, `--set POINTER=JSON` | Configuration selection above. | | `--input-file PATH` | Required source input file. | | `--lane ID` | Repeat to select literal artifact lane IDs; commas are part of an ID, not separators. | | `--output-dir PATH` | Nonempty invocation-relative override of the output root. | | `--cache auto\|bypass\|refresh` | Invocation-wide selection over binding and pipeline cache controls. | | `--reference SELECTOR=PATH` | Repeatable external reference bind. | | `--without-reference SELECTOR` | Repeatable external reference unbind. | | `--debug[=true\|false]` | Native debug verbosity and independent run capture selection. | | `--debug-dir PATH` | Capture destination override; explicit empty disables capture. | | `--llm-profile ID`, `--llm-session-id ID` | Native resource/session selections below. | | `--llm-*` execution controls | Run-wide request overrides below. | | `--format`, `--quiet`, `--verbose`, `--progress` | Native presentation controls below. | A directory alone does not enable capture. A nonempty debug-directory override can re-enable capture over an empty configured root, but still needs debug selection. `--debug --quiet` captures while suppressing stdout; `--quiet --debug` selects debug visibility and capture. `--debug=false` disables capture. Debug on inspection commands changes native visibility without allocating a pipeline bundle. [Configuration](config.md#concurrency-output-cache-and-debug) defines directory defaults; [Operations](operations.md) owns capture lifecycle. Example using the maintained minimal configuration and input: ~~~sh notarius run dnd-session --config examples/dnd-minimal/config.yml \ --input-file examples/dnd-minimal/transcript.json --format json ~~~ This run uses a configured provider and needs its credentials when required. Offline validation does not. ### Run-wide LLM Overrides These canonical ckprompt flags reach initial producers, semantic corrections, and LLM validators on the shared native engine without mutating configuration: | Flag | Value | | --- | --- | | `--llm-profile` | Exact profile ID; qualified for collection resources. | | `--llm-session-id` | Session selection. | | `--llm-endpoint` | Native endpoint override. | | `--llm-model` | Model override. | | `--llm-temperature` | Numeric temperature. | | `--llm-max-tokens` | Integer token limit. | | `--llm-top-p` | Numeric top-p. | | `--llm-timeout-seconds` | Integer native request timeout. | | `--llm-service-tier` | Service tier selection. | | `--llm-reasoning-effort` | Reasoning selection; explicit empty suppresses inherited reasoning. | | `--llm-api-key-env` | Credential environment-variable name, not its value. | | `--llm-transient-retries` | Integer native transient-failure retry selection; explicit zero disables these retries. | | `--llm-extra-params` | JSON provider-parameter object, preserving false/zero/null values. | Omitted values remain unspecified, not the display defaults in help. `--llm-temperature=0` and `--llm-reasoning-effort=` retain their supplied meaning. Native target validation and provider-map rules apply; this interface does not add a repair-model selection, structural-repair count, or generic stage retry. Use application configuration for semantic turns and native prompt configuration for structural contracts. Omitted profile selection preserves binding/pipeline/prompt precedence. Explicit `--llm-profile=` clears the application profile selection so native prompt default selection applies. Without an explicit session flag, Notarius generates a stable `notarius:v1:` session from the trimmed resolved input module key and exact raw input bytes, independent of references and pipeline/profile settings. An explicit value replaces it; explicit empty clears that generated selection and leaves native prompt/session behavior in control. Sessions are provider-visible correlation identifiers, not secret storage. PromptKit convenience spellings are scoped to `promptkit` commands; run uses the canonical `--llm-*` names above. [Native request validation][requests] documents execution controls in detail. ### Reference Selectors Bind declared slots using `--reference SELECTOR=PATH`: | Selector | Target | | --- | --- | | `slot` | Every selected compatible target declaring the slot. | | `chunk.slot` | Chunker. | | `lane.slot` | Compatible extract/merge/normalize bindings in that lane. | | `lane.extract.slot` | That lane's extractor. | | `lane.merge.slot` | That lane's merger. | | `lane.normalize.slot` | That lane's normalizer. | Pipeline/lane selectors may match several targets and fail if they match none. A binding-specific selector requires its selected target to declare the slot. There is no stage-wide merger shorthand. CLI paths override configured external paths; narrower selectors beat broader ones, with last occurrence winning at equal scope. Binding and unbinding the same concrete target at equal scope fails; narrower actions can make intentional exceptions to broader actions. `--without-reference` uses the selector without `=PATH`. It removes external bindings only. Neither action replaces/removes generated handoffs; collisions fail resolution and required slots must remain bound. CLI paths use the invocation working directory. Configuration defines slot compatibility and path origins in [References And Ordered Handoffs](config.md#references-and-ordered-handoffs). For a complete D&D workflow, pipeline-level references are first-class inputs: ~~~sh notarius run dnd-session --config examples/dnd-complete/config.yml \ --input-file examples/dnd-complete/transcript.json \ --reference party=/data/references/party.txt \ --reference glossary=/data/references/glossary.txt \ --output-dir /data/results --format json ~~~ ### Completion Report Successful runs publish domain files and finalize requested capture before reporting one small value: | Field | Meaning | | --- | --- | | `pipeline` | Selected pipeline ID. | | `artifact_count` | Published deliverable files, including reused artifacts and enabled auxiliaries; excludes intermediates/cache/debug. | | `output_directory` | Absolute run-specific publication directory, not the configured root. | | `debug_directory` | Optional absolute run capture directory; omitted when disabled. | | `fallback_count` | Producer operations that emitted fallback, present only when positive. | Text summarizes pipeline, count, and path, appending capture location when available. Fallback success is explicitly qualified, even when warnings are hidden. Affected downstream artifacts, attempts, and validators are not extra fallbacks. JSON/YAML serialize the same value; report format does not change domain artifact encoding. There is no persisted receipt, execution ledger, universal envelope, or automatic duplicate report file. Consumers check status, optionally decode the report, and read configured lane/auxiliary paths. A failed stdout write may leave partial bytes. A failure after publication can leave valid artifacts; the failure explanation identifies available paths. [JSON output](integrations/json-output.md) owns logical artifact paths and payload contracts, not this report. ## Configuration Commands The native scopes are `app` (default) and `promptkit`. Both inspect the same application-owned load; the latter focuses native PromptKit settings. Use `config scopes` for supported operations. No inspection command implicitly runs a pipeline or provider. ~~~sh notarius config validate --config examples/dnd-minimal/config.yml notarius config show --scope app --config examples/dnd-minimal/config.yml notarius config sources --config examples/dnd-complete/config.yml notarius config explain --config examples/dnd-minimal/config.yml \ --path /concurrency/workers --format json notarius config show --scope promptkit --config examples/dnd-minimal/config.yml notarius config diff --config examples/dnd-minimal/config.yml \ --against-config examples/dnd-complete/config.yml --check ~~~ Show supports `--path`; explain supports `--list`, `--path`, and native history/ filter options. Focused PromptKit paths retain the `/promptkit` prefix, for example `/promptkit/collections/notarius/profiles`. Diff accepts separate right-side configuration, overlay, and assignment inputs; differences with `--check` yield status 3. These commands report native values and secret-aware source evidence, not copied Notarius inspection objects. Consult [native configuration commands][configuration] for complete report and comparison semantics. Use `pipeline validate`, not configuration validation, for production module/reference/resource preflight. ## PromptKit Commands The installed native suite includes: - listings of prompts, profiles, backends, namespaces, and collections; - inspection of a named prompt, profile, or backend; - requirements discovery, concrete request validation, and prepared preview; - explicit smoke tests: `reachability`, `authentication`, `text_inference`, `structured_output`, or `all`. ~~~sh notarius promptkit list prompts --config examples/dnd-minimal/config.yml \ --namespace notarius notarius promptkit show profile notarius/dnd-extraction \ --config examples/dnd-minimal/config.yml --format json notarius promptkit requirements show notarius/dnd.spells \ --config examples/dnd-minimal/config.yml ~~~ Resource/requirements inspection needs no transcript, credential values, or provider call. Profile reports describe the stored profile before backend completion and request overrides; partial profiles are valid. Request validation and `show prepared` actually prepare native requests and may read supplied resources or require credentials according to the target, but do not call a model. Prepared reports can contain rendered application data. Use `--llm-var KEY=VALUE`, `--llm-input-text NAME=TEXT`, or `--llm-input-file NAME=PATH` for concrete prompt inputs. These are not the pipeline's source input. Namespace flags choose namespaces for short IDs; already-qualified IDs remain unchanged. Native convenience aliases are installed only on their applicable PromptKit commands; use help to see them. Smoke tests are explicit and may contact providers or perform inference. Read support, applicability, and observation results; status zero alone does not mean every observation passed. Neither debug nor inspection silently launches a smoke test. Full native mechanics are documented under [inspection][inspection], [preview][preview], [requirements][requirements], [resource listings][catalogs], and [smoke tests][smoke]. ## Output Streams And Exit Statuses Results go to stdout; failures, native diagnostics, and progress go to stderr. `--format text|json|yaml` selects report presentation. Default run presentation uses its human template; other structured native reports ordinarily use YAML. `--format` does not reformat help, completion scripts, diagnostics, or domain payloads. Only one visibility mode is active; the last enabled `--quiet`, `--verbose`, or `--debug` wins. Ordinary mode hides optional warning/info/debug messages; verbose shows warning/info; debug adds debug and default progress. Explicit `--progress=false` disables progress, and quiet suppresses it. Quiet suppresses stdout but retains failure explanations; formatting errors can still fail a quiet command. Run capture selection remains independent of that final mode. `--format json --verbose` keeps successful stdout report-only JSON while useful diagnostics go to stderr. No application-wide structured error envelope is introduced; failed stdout is not a success document. | Status | Meaning | | --- | --- | | `0` | Command completed, including supported permissive fallback with report qualification. | | `1` | Operational failure, cancellation, publication/capture/presentation failure, or an unclassified/mixed failure. | | `2` | Invalid invocation or identifiable invalid configuration. | | `3` | Native configuration differences with diff check mode. | Native causes and classification remain intact. Not every resource/preflight failure is identifiable invalid configuration. Rendering or diagnostic delivery failure can change an otherwise successful result to failure; callers check the actual process status. See [native outcomes][outcomes] for library conventions. [native-cli]: https://forge.maximumdirect.net/base-layer/commandkit/src/tag/v0.7.0/docs/cli.md [syntax]: https://forge.maximumdirect.net/base-layer/commandkit/src/tag/v0.7.0/docs/cli.md#registered-command-syntax [configuration]: https://forge.maximumdirect.net/base-layer/commandkit/src/tag/v0.7.0/docs/cli.md#configuration-scopes [requests]: https://forge.maximumdirect.net/base-layer/commandkit/src/tag/v0.7.0/docs/cli.md#concrete-request-validation [inspection]: https://forge.maximumdirect.net/base-layer/commandkit/src/tag/v0.7.0/docs/cli.md#promptkit-definition-inspection [preview]: https://forge.maximumdirect.net/base-layer/commandkit/src/tag/v0.7.0/docs/cli.md#promptkit-prepared-request-preview [requirements]: https://forge.maximumdirect.net/base-layer/commandkit/src/tag/v0.7.0/docs/cli.md#promptkit-requirements [catalogs]: https://forge.maximumdirect.net/base-layer/commandkit/src/tag/v0.7.0/docs/cli.md#promptkit-catalogs [smoke]: https://forge.maximumdirect.net/base-layer/commandkit/src/tag/v0.7.0/docs/cli.md#promptkit-smoke-testing [outcomes]: https://forge.maximumdirect.net/base-layer/commandkit/src/tag/v0.7.0/docs/cli.md#outcome-status