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 serve [--config <path>]
distributor validate [--format text|json] <path>
distributor validate --config <path> --pipeline <id> [--bundle <path>] [--format text|json]
distributor inspect [--format text|json] <path>
distributor inspect --config <path> --pipeline <id> [--bundle <path>] [--format text|json]
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.
• serve: loads a YAML config, resolves HTTP upload bearer tokens, and runs the HTTP upload API.
• validate: validates a local source bundle directory, a local source bundle tree, or one configured pipeline source.
• inspect: validates source bundles and prints normalized bundle metadata for a local path or one configured pipeline source.
• manifest create: creates manifest.json for a local source bundle directory.

validate and inspect have two mutually exclusive modes: a local path shortcut, or configured source mode with --config <path> --pipeline <id>. Configured source mode opens only the selected pipeline source and supports configured local, ssh, and s3 sources. It does not open destinations. run executes configured local, ssh, and s3 sources and destinations. serve executes configured http_upload sources through the upload API and normal destination fan-out.

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.

serve flags:

• --config <path>: config file to load. If omitted, serve uses /usr/local/etc/distributor/config.yml.

validate and inspect configured source flags:

• --config <path>: config file to load for source validation or inspection. Required in configured source mode.
• --pipeline <id>: pipeline source to validate or inspect. Required in configured source mode.
• --bundle <path>: source-root-relative bundle directory to validate or inspect instead of discovering every bundle under the source root.

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 in local mode. Local paths cannot be combined with --config, --pipeline, or --bundle.

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

Validate a configured source without opening destinations:

go run ./cmd/distributor validate --config examples/local-publish.yml --pipeline example-source-bundle

Inspect one configured source bundle:

go run ./cmd/distributor inspect \
  --config <config-path> \
  --pipeline <pipeline-id> \
  --bundle daily/2026-06-01

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

Start the HTTP upload API:

DISTRIBUTOR_EXAMPLE_UPLOAD_TOKEN=<token> \
  go run ./cmd/distributor serve --config examples/http-upload-local.yml

Upload an archive to the configured http_upload pipeline associated with a bearer token:

curl -X POST http://127.0.0.1:8080/upload \
  -H "Authorization: Bearer $DISTRIBUTOR_EXAMPLE_UPLOAD_TOKEN" \
  -H "Content-Type: application/gzip" \
  --data-binary @bundle.tar.gz

The upload response is accepted asynchronously:

{"run_id":"reports.20260603T120000Z.abcdef12","status":"accepted"}

Check upload status:

curl http://127.0.0.1:8080/runs/<run-id>

Check server readiness:

curl http://127.0.0.1:8080/healthz

Preview local fan-out publication:

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

Preview local archive-plus-latest publication:

go run ./cmd/distributor run --config examples/archive-and-latest.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 source bundle path, destination id, destination backend, action, outputs, and reason. Fixed path destinations also print path_mapping=fixed target=. to show that the selected bundle targets the destination backend root. 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.

Dry-run output for fixed path destinations prints a warning with the candidate count and selected source bundle. If a fixed path dry run plans a destructive replacement, it prints an additional warning that the destination root would be replaced.

The final status line includes counters for publish_new, replace_older, force_replace, skipped destinations, failures, whether the run was a dry run, and fixed path destinations.

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. Configured source results also include pipeline id and source backend.
• inspect: bundle path, id, created timestamp, digest, file count, total size, and manifest file records. Configured source results also include pipeline id and source backend.
• manifest create: manifest path, bundle root, id, created timestamp, digest, file count, and file records.
• run: dry-run status, pipeline summaries, destination action records, destination bundle paths, path mapping markers, optional primary URLs, output records with optional URLs, 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 configured source mode when the bundle is already on an SSH or S3 source. 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.