eric/notarius
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Document subprocess run results

Browse Source
This commit is contained in:
Eric Rakestraw
2026-07-26 17:22:27 +00:00
parent 0d947549fb
commit 1da29e6788
9 changed files with 170 additions and 9 deletions
Download Patch File Download Diff File Expand all files Collapse all files

26
docs/cli.md
View File

@@ -10,7 +10,7 @@ defined in [Operations](operations.md).
~~~
notarius help
notarius run <pipeline-id> --input path/to/source.json [flags]
notarius run <pipeline-id> --input path/to/source.json [--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]
~~~
@@ -21,7 +21,7 @@ writes the command summary to standard output and exits with status 0.
## run
~~~
notarius run <pipeline-id> --input path/to/source.json [flags]
notarius run <pipeline-id> --input path/to/source.json [--json] [flags]
~~~
The **run** command executes the named pipeline for one input file. The
@@ -32,6 +32,7 @@ pipeline ID and **--input** are required.
| **--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. |
| **--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**. |
@@ -70,11 +71,18 @@ names, requiredness, and configured bindings are part of the
### 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).
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
warnings reports the warning count to standard error. The published JSON bundle
is defined by the [JSON output contract](integrations/json-output.md).
With **--json**, successful standard output is exactly one
`notarius.run-result.v1` 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.
Example:
@@ -134,6 +142,10 @@ go run ./cmd/notarius pipelines list \
Successful commands write their primary result to standard output. Warnings and
errors are written to standard error.
For **run --json**, 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.
| Status | Meaning |
| --- | --- |
| 0 | The command completed successfully, including root help. |