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

Add JSON output format for CLI commands

Browse Source
This commit is contained in:
Eric Rakestraw
2026-06-01 20:44:27 +00:00
parent 0382978af0
commit e51bc28b05
13 changed files with 849 additions and 48 deletions
Download Patch File Download Diff File Expand all files Collapse all files

39
docs/cli.md
View File

@@ -12,10 +12,10 @@ This discovers the example source bundle and publishes source files to `workspac
```sh
distributor [--help]
distributor version
distributor run [--config <path>] [--dry-run] [--force]
distributor validate <path>
distributor inspect <path>
distributor version [--format text|json]
distributor run [--config <path>] [--dry-run] [--force] [--format text|json]
distributor validate [--format text|json] <path>
distributor inspect [--format text|json] <path>
```
- `version`: prints the application name and version. Development builds print `distributor dev`.
@@ -35,6 +35,10 @@ All subcommands:
- `--help`, `-h`: print command-specific help.
Output-producing subcommands:
- `--format text|json`: output format. `text` is the default. Help and usage output are always text.
`run` flags:
- `--config <path>`: config file to load. If omitted, `run` uses `/usr/local/etc/distributor/config.yml`.
@@ -89,7 +93,9 @@ go run ./cmd/distributor run --config <config-path> --dry-run --force
## Output
`run` prints the number of configured pipelines, one line per pipeline, one line per planned destination action, and a final status line. Destination action lines include the bundle path, destination id, destination backend, action, outputs, and reason. Actions include:
Text output is the default and is intended for humans.
`run` text output prints the number of configured pipelines, one line per pipeline, one line per planned destination action, and a final status line. Destination action lines include the bundle path, destination id, destination backend, action, outputs, and reason. Actions include:
- `publish_new`: destination has no managed state and is empty.
- `replace_older`: destination state is older than the source manifest.
@@ -102,6 +108,29 @@ The command exits non-zero if any destination fails. Independent later destinati
The final status line includes counters for `publish_new`, `replace_older`, `force_replace`, skipped destinations, failures, and whether the run was a dry run.
JSON output writes exactly one JSON document to stdout:
```json
{
"schema_version": 1,
"command": "inspect",
"ok": true,
"warnings": [],
"result": {}
}
```
Warnings are objects in the top-level `warnings` array and are not printed again as text. Fatal setup errors, such as a missing config file or invalid arguments, write no JSON document and return a non-zero exit code with a text error on stderr.
`run --format json` returns partial results when destination failures occur after planning or execution begins. In that case stdout contains `ok: false`, a `result` with pipeline summaries, destination actions, final counters, and a top-level `errors` array; the process still exits non-zero.
Command-specific JSON results:
- `version`: application name and version.
- `validate`: bundle count and discovered bundle identifiers.
- `inspect`: bundle path, id, created timestamp, digest, file count, total size, and manifest file records.
- `run`: dry-run status, pipeline summaries, destination action records, output records, final counters, warnings, and partial failure records.
## Diagnostics
Use `validate` before publication when a producer has written a new bundle. Use `inspect` to confirm normalized ids, timestamps, digests, file paths, and file sizes.