Rewrite configuration and CLI references for native commands

This commit is contained in:
2026-11-22 06:20:54 +00:00
parent 3cf389db78
commit 5e58327032
3 changed files with 673 additions and 845 deletions

View File

@@ -1,299 +1,367 @@
# 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).
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.
Configuration-consuming commands share the same selection: explicit `--config`,
then `NOTARIUS_CONFIG`, then working-directory, user, and system searches. A
selected file's loading failure is terminal. Reports use that selected source;
the [configuration reference](config.md#configuration-discovery-and-precedence)
defines the filename groups and value precedence. Use `--config` for a fixed
service or subprocess selection.
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
~~~
notarius help
notarius --version
notarius run <pipeline-id> --input path/to/source.json [--json] [flags]
notarius config validate [--config path/to/config.yml] [--config-overlay name] [--pipeline pipeline-id] [--only lane-a,lane-b]
notarius config effective [--scope notarius|promptkit] [--config path/to/config.yml] [--config-overlay name]
notarius config explain [--scope notarius|promptkit] [--config path/to/config.yml] [--config-overlay name] <json-pointer>
notarius config profile [--config path/to/config.yml] [--config-overlay name] <profile-id>
notarius pipelines list [--config path/to/config.yml] [--config-overlay name] [--json]
~~~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
~~~
Running Notarius without arguments, or with **help**, **--help**, or **-h**,
writes the command summary to standard output and exits with status 0.
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.
`notarius --version` is valid only as the sole root argument. It writes exactly
`notarius <version>` followed by a newline to standard output and exits with
status 0. A tagged `go install` build can report its main-module stable tag,
and controlled builds can inject a stable tag at link time through
`gitea.maximumdirect.net/eric/notarius/internal/buildinfo.Override`; an ordinary
unversioned checkout reports `development`. Invalid injected version content is
a runtime error with exit status 1, while extra `--version` arguments are a
syntax error with exit status 2. This diagnostic does not replace the
[run-result](integrations/run-result.md) or artifact contracts for downstream
compatibility decisions.
`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.
## run
## Syntax And Supplied Values
~~~
notarius run <pipeline-id> --input path/to/source.json [--json] [flags]
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 **run** command executes the named pipeline for one input file. The
pipeline ID and **--input** are required.
The value is JSON, so strings require JSON quoting. Preserve shell quoting:
| Flag | Meaning |
~~~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** | Use this configuration file. When omitted, configuration discovery applies; see [Configuration](config.md). |
| **--config-overlay name** | Select a ConfigKit configuration overlay. Empty and **default** select the composed base configuration. |
| **--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 external file reference bindings at pipeline, lane, chunk, or binding scope. Repeatable. |
| **--without-reference selector** | Remove matching configured external reference bindings. Repeatable. |
| `--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. |
**--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).
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.
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 reference slots declared by the selected
configured targets. Qualification narrows the scope of an override:
| Form | Target |
| --- | --- |
| slot=path | Every selected target that declares slot. |
| chunk.slot=path | The chunker. |
| lane.slot=path | Every 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. |
Pipeline- and lane-scoped selectors are expected to match multiple targets and
fail if they match none. A stage-specific selector fails when its lane is not
selected or its target does not declare the slot. There is no stage-wide
`merge.slot` shorthand; name the lane when targeting a merger.
CLI bindings override configured external paths. For overlapping CLI
selectors, a binding-specific or chunk selector overrides a lane selector, and
a lane selector overrides a pipeline selector. The last occurrence wins at
equal scope. Binding and unbinding the same concrete target at equal scope is
an error; a narrower bind or unbind may create an intentional exception to a
broader action.
**--without-reference** uses the same selector forms without `=path` and
removes external bindings only. Neither flag replaces or removes a generated
artifact handoff; an external/generated collision is a resolution error.
Required slots are checked after all effective changes. CLI reference paths
are resolved relative to the process working directory, so subprocess and
service callers should use absolute paths. Slot names, accepted media types,
size limits, requiredness, and configured generated bindings are part of the
[configuration contract](config.md).
For example, one shared campaign reference can reach every compatible target,
with an optional lane-specific exception:
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
~~~
notarius run dnd-session \
--input /data/transcript.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 npc-registry.party=/data/references/npc-party-context.txt
--reference glossary=/data/references/glossary.txt \
--output-dir /data/results --format json
~~~
### Run output
### Completion Report
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
actionable process warnings reports their group and occurrence counts to
standard error. When the selected output module publishes `warnings.json`, the
summary also reports that durable file's path. Advisory and observation findings
do not produce a warning line. The published JSON bundle
is defined by the [JSON output contract](integrations/json-output.md).
Successful runs publish domain files and finalize requested capture before
reporting one small value:
With **--json**, successful standard output is exactly one
`notarius.run-result.v2` 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.
| 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. |
Example:
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.
~~~
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
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
~~~
## config validate
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.
~~~
notarius config validate [--config path/to/config.yml] [--config-overlay name] [--pipeline pipeline-id] [--only lane-a,lane-b]
## 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
~~~
This command loads and validates the selected composed configuration. With **--pipeline**, it also
resolves that pipeline against the production module catalog. **--only** selects
lanes during that resolution and requires **--pipeline**.
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.
Success is written to standard output as either config "<path>" is valid or
config "<path>" is valid for pipeline "<pipeline-id>".
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.
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.
## config effective
~~~
notarius config effective [--config path/to/config.yml] [--config-overlay name]
~~~
This command writes the selected composed configuration as deterministic,
redacted YAML. By default, it reports the Notarius configuration. Set
**--scope promptkit** to report PromptKit's captured effective configuration;
**--scope notarius** is equivalent to the default. Only the PromptKit scope
constructs the PromptKit inspection engine, using the selected configuration
and registered application assets. Engine construction validates and captures
the definitions. Standard output contains only the selected report: the
command does not validate a pipeline, prepare modules, materialize references,
resolve credentials, or contact a provider. PromptKit output can include
ordinary inline prompt and provider-parameter data; credential-shaped provider
parameters are redacted.
## config explain
~~~
notarius config explain [--config path/to/config.yml] [--config-overlay name] <json-pointer>
~~~
This command writes a redacted, human-readable explanation for one canonical
JSON Pointer. Supply `""` explicitly to explain the root. By default, it
explains Notarius configuration; **--scope promptkit** selects PromptKit
configuration history, while **--scope notarius** is equivalent to the default.
A malformed pointer is a syntax error; a well-formed unknown path is a command
failure. The explanation can describe values displaced by source overlays or
imports. Standard output contains only the selected explanation. PromptKit
scope constructs and validates its captured definitions, and its report can
include ordinary inline prompt and provider-parameter data.
## config profile
~~~
notarius config profile [--config path/to/config.yml] [--config-overlay name] <profile-id>
~~~
This command inspects one exact, nonblank PromptKit profile ID and writes one
JSON object followed by a newline:
The following illustrates the JSON shape; field values vary with the selected
profile and its configured backend.
~~~json
{"profile_id":"example","api_key_required":true,"effective_model_params":{"backend_id":"openrouter","endpoint":"https://provider.example/v1","model":"example-model","temperature":0,"max_tokens":0,"top_p":0,"timeout_seconds":600,"service_tier":"","reasoning_effort":"","api_key_env":"PROVIDER_API_KEY","extra_params":null}}
~~~
The object reports the resolved target, including backend-completed endpoint
and credential-name settings. An empty **backend_id** identifies an
endpoint-only profile. Credential names and **api_key_required** are configured
metadata; the command does not look up credential values or report whether an
environment variable is set. Credential-shaped keys in **extra_params** are
redacted.
This is the named profile's configured target, not a prediction of provider
defaults or the profile selected by an individual request. A request may omit
its profile and let its prompt select a default, and a run may supply a profile
override; this command applies neither behavior. Zero-valued fields show the
effective value but do not distinguish omission from an explicit zero. Use
[effective configuration](#config-effective) and
[configuration explanation](#config-explain) to inspect source presence and
history. Profile/configuration failures use exit status 1; malformed command
syntax, a blank ID, or an incorrect argument count use exit status 2. No
transcript or model call is involved.
## pipelines list
~~~
notarius pipelines list [--config path/to/config.yml] [--config-overlay name] [--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
~~~
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
Successful commands write their primary result to standard output. Warnings and
errors are written to standard error.
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.
Configuration load errors include ConfigKit's field diagnostics and source
coordinates, followed by a source-ID legend identifying the acquired files or
source labels. This includes imported files and the selected configuration overlay.
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.
For **run --json**, actionable process 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.
`--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 | 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. |
| `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. |
The root help spellings are the supported help path. Invoking **--help** on
**run**, a **config** subcommand, 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.
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

File diff suppressed because it is too large Load Diff

View File

@@ -1894,6 +1894,28 @@ implemented behavior. Check ADR status links and accepted-body preservation;
## Stage 39: Rewrite Canonical Configuration And CLI References
**Status:** Complete. Rewrote the canonical configuration and CLI references for
version 6, shared native source selection/companions, whole-record resource
replacement and inheritance, null/presence and schema-root semantics, qualified
profiles, workers, semantic turns, strict/permissive modes, and unified reuse
controls. Documented native pipeline/standard commands, supplied/repeated values,
references, complete run-wide execution overrides, presentation/streams, the small
completion report, and outcome classifications. Removed retired syntax and old
example paths rather than preserving compatibility examples. Native default
repair/retry and backend admission remain upstream-owned. Retained domain module,
reference-slot, output-option, and default-validator definitions, checking all 20
D&D extract/normalize chains against the real resolved complete pipeline.
Compared declarations, configuration/resolver tests, actual help, maintained
examples, and the selected upstream module documentation. Twenty direct offline
help/completion/configuration/inspection/preflight/diff checks pass with the
OpenRouter credential variable unset; assignment/explicit-zero examples also
pass. All 46 local links/anchors and 20 pinned upstream destinations/anchors
resolve against repository/module sources. Whole-tree tests, vet, a temporary
executable build with `GOWORK=off`, and `git diff --check` pass. No live inference
or real credential was used. Operations, migration, integration, and internal
documentation retain their following assigned stages.
**Goal:** operators can configure and invoke only the implemented native surface.
**Inspect/change:** `docs/config.md`, `docs/cli.md`, final command declarations,