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]
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 and ssh backends. S3 config can be parsed and validated, but configured S3 execution fails with a clear unsupported-execution error.

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 files.

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

Output

run prints the number of configured pipelines, one line per pipeline, one line per planned destination action, and a final status line. Actions include:

publish_new: destination has no managed state and is empty.
replace_older: destination state is older than the source manifest.
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.

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.2 KiB Raw Blame History