distributor/docs/cli.md

Distributor CLI

Shortest useful command

go run ./cmd/distributor run --config examples/local-publish.yml

This discovers the example source bundle and publishes source files to workspace/published/source-bundle.

Command overview

distributor [--help]
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>
distributor manifest create <bundle-path> --id <bundle-id> [options]

• version: prints the application name and version. Development builds print distributor dev.
• run: loads a YAML config, discovers source bundles, plans each configured destination, writes selected outputs unless --dry-run is set, and prints a final status summary.
• validate: validates a local source bundle directory or a local tree containing source bundles.
• inspect: validates local source bundles and prints normalized bundle metadata.
• manifest create: creates manifest.json for a local source bundle directory.

validate and inspect accept local paths only. run executes local, ssh, and s3 backends.

Flag reference

Root command:

• --help, -h, or help: print root help.

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.
• --dry-run: load config, discover bundles, inspect destination state, print planned actions and final status, and do not write output files, destination state, or SSH known_hosts entries.
• --force: allow explicit destructive replacement for supported conflict cases in this run only.

manifest create flags:

• --id <bundle-id>: source bundle id. Required.
• --file <path>: bundle-relative file to include. Repeatable. If omitted, files are scanned recursively.
• --created <time>: RFC3339 source created timestamp. If omitted, the current UTC time is used.
• --overwrite: replace an existing manifest.json.

run does not accept positional arguments. validate and inspect accept at most one path; omitting the path returns a required-path error.

Common workflows

Validate a source bundle:

go run ./cmd/distributor validate examples/source-bundle

Inspect a source bundle:

go run ./cmd/distributor inspect examples/source-bundle

Create a manifest for a local producer bundle:

go run ./cmd/distributor manifest create <bundle-path> --id <bundle-id>

Create a manifest with explicit file order:

go run ./cmd/distributor manifest create <bundle-path> \
  --id <bundle-id> \
  --created 2026-06-01T11:00:00Z \
  --file report.md \
  --file summary.txt

Preview local publication without writing:

go run ./cmd/distributor run --config examples/local-publish.yml --dry-run

Publish the local source example:

go run ./cmd/distributor run --config examples/local-publish.yml

Publish the local HTML example:

go run ./cmd/distributor run --config examples/local-html.yml

Preview local fan-out publication:

go run ./cmd/distributor run --config examples/fan-out.yml --dry-run

Preview a forced replacement before publishing:

go run ./cmd/distributor run --config <config-path> --dry-run --force

Output

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.
• force_replace: --force requested a supported destructive replacement.
• skip_same: destination state already matches the source manifest.
• skip_destination_newer: destination state is newer than the source manifest.
• error: planning or execution failed for that destination.

The command exits non-zero if any destination fails. Independent later destinations are still attempted.

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:

{
  "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.
• manifest create: manifest path, bundle root, id, created timestamp, digest, file count, and file records.
• run: dry-run status, pipeline summaries, destination action records, output records, final counters, warnings, and partial failure records.

Diagnostics

Use manifest create when a local producer has written bundle files but not manifest.json. 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.

For symptom-oriented recovery steps, see troubleshooting. For destination state and retry behavior, see operations. For config fields and defaults, see configuration.