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
distributor run [--config <path>] [--dry-run] [--force]
distributor validate <path>
distributor inspect <path>

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.

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.

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.

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

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

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:

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.

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.

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

3.8 KiB Raw Blame History