distributor/docs/cli.md

Distributor CLI

Audience: operators, integrators, and developers who run distributor from a shell or automation.

This document is the canonical command and flag reference. Configuration schema details live in Configuration, operational recovery guidance lives in Operations, failure diagnosis lives in Troubleshooting, and external contracts live under Integrations.

Shortest Useful Command

Run the maintained local publishing example from the repository root:

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

The example reads examples/source-bundle/manifest.json, publishes the configured files into workspace/published/source-bundle, and writes destination state metadata beside the published output.

Command Overview

distributor [--help]
distributor help
distributor version [--format text|json]
distributor run [--config <path>] [--dry-run] [--force] [--format text|json]
distributor reconcile-state --config <path> --pipeline <id> --destination <id> [--all-owners] [--dry-run] [--format text|json]
distributor prune --config <path> --pipeline <id> --destination <id> (--dry-run|--apply) [--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
distributor manifest create <bundle-path> --id <bundle-id> [options]
distributor manifest create --id <bundle-id> [options] <bundle-path>

• version prints the application name and version.
• run executes configured pipelines against their destinations.
• reconcile-state repairs destination state records for missing managed outputs.
• prune deletes managed outputs selected by the destination retention policy when --apply is supplied.
• serve starts the authenticated HTTP upload API defined by the configuration file.
• validate checks a local bundle path or a configured source bundle.
• inspect reports manifest and file metadata for a local bundle path or a configured source bundle.
• manifest create writes a manifest.json file for an existing bundle directory.

Flag Reference

Help

distributor, distributor --help, distributor -h, distributor help, and distributor manifest print command help. Unknown commands and invalid argument combinations print usage guidance and exit non-zero.

Common Output Format

--format text|json is supported by version, run, reconcile-state, prune, validate, inspect, and manifest create.

• text is the default human-readable output.
• json emits one JSON document for successful command execution.
• Invalid formats are rejected before command execution.

version

distributor version [--format text|json]

version accepts no positional arguments. Text output prints the application name and version; JSON output includes application and version fields.

run

distributor run [--config <path>] [--dry-run] [--force] [--format text|json]

• --config <path> loads the pipeline configuration. If omitted, the application uses /usr/local/etc/distributor/config.yml.
• --dry-run validates inputs and reports destination actions without applying changes.
• --force permits exceptional catalog replacement when a dry run reports force_replace for unmanaged content, a planned unmanaged path collision, invalid state, or unsupported future state.
• --format text|json selects human-readable or machine-readable output.

run accepts no positional arguments.

reconcile-state

distributor reconcile-state --config <path> --pipeline <id> --destination <id> [--all-owners] [--dry-run] [--format text|json]

• --config <path> loads the pipeline configuration and is required.
• --pipeline <id> selects the pipeline used to identify the destination root and is required.
• --destination <id> selects the destination root and is required.
• --all-owners repairs missing managed output records for every owner in the selected catalog state file. Without it, repair is scoped to the selected pipeline and destination owner.
• --dry-run reports repairs without rewriting .distributor.json.
• --format text|json selects human-readable or machine-readable output.

Without --dry-run, reconcile-state applies state repair by removing records for managed outputs that no longer exist in storage. It reports unmanaged entries but does not delete destination files, adopt unmanaged files, or validate output digests. The command accepts no positional arguments.

prune

distributor prune --config <path> --pipeline <id> --destination <id> (--dry-run|--apply) [--format text|json]

• --config <path> loads the pipeline configuration and is required.
• --pipeline <id> selects the pipeline used to identify the destination root and owner scope.
• --destination <id> selects the destination root and owner scope.
• --dry-run reports planned managed-output deletes without deleting outputs or rewriting .distributor.json.
• --apply deletes planned managed outputs and rewrites .distributor.json after confirmed deletes.
• --format text|json selects human-readable or machine-readable output.

Exactly one of --dry-run or --apply is required. The command uses only the selected destination's configured retention.prune policy; it does not accept one-off retention overrides. Apply mode deletes only planned managed output paths, preserves unmanaged files, and preserves .distributor.json even when no managed outputs remain.

serve

distributor serve [--config <path>]

• --config <path> loads HTTP, source, destination, and pipeline configuration. If omitted, the application uses /usr/local/etc/distributor/config.yml.

serve accepts no positional arguments and runs until interrupted or until the server exits with an error.

validate

distributor validate [--format text|json] <path>
distributor validate --config <path> --pipeline <id> [--bundle <path>] [--format text|json]

validate has two source modes:

• Local path mode validates the bundle at <path>.
• Configured source mode resolves the source from --config <path> and --pipeline <id>.

Configured source flags:

• --config <path> loads the configuration file.
• --pipeline <id> selects the configured pipeline source to validate.
• --bundle <path> overrides the configured source bundle path for the selected pipeline.
• --format text|json selects output format.

A local positional path cannot be combined with --config, --pipeline, or --bundle. When any configured source flag is used, both --config and --pipeline are required.

inspect

distributor inspect [--format text|json] <path>
distributor inspect --config <path> --pipeline <id> [--bundle <path>] [--format text|json]

inspect uses the same source mode rules as validate, then reports bundle metadata instead of only validation status. Local path mode requires exactly one bundle path. Configured source mode requires both --config and --pipeline; --bundle may override the selected pipeline source path.

manifest create

distributor manifest create <bundle-path> --id <bundle-id> [options]
distributor manifest create --id <bundle-id> [options] <bundle-path>

Flags may appear before or after the bundle path. Both --flag value and --flag=value forms are accepted.

• --id <bundle-id> sets the manifest bundle identifier and is required.
• --created <timestamp> sets the manifest creation timestamp. If omitted, the current UTC time is used.
• --file <relative-path> includes one file in the manifest. The flag may be repeated.
• --overwrite allows replacing an existing manifest.json file.
• --format text|json selects output format.

If no --file flags are provided, manifest create scans the bundle directory recursively. The command requires exactly one bundle path, refuses unsafe manifest paths, and writes manifest.json at the bundle root.

Common Workflows

Validate Or Inspect A Local Bundle

go run ./cmd/distributor validate examples/source-bundle
go run ./cmd/distributor inspect --format json examples/source-bundle

Validate Or Inspect A Configured Source

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

Use --bundle <path> with configured source mode when automation needs to validate or inspect an alternate bundle path through the selected pipeline configuration.

Create A Manifest

go run ./cmd/distributor manifest create examples/source-bundle --id example-source-bundle --overwrite
go run ./cmd/distributor manifest create --id example-source-bundle --overwrite examples/source-bundle

Use repeated --file flags when the manifest should include an explicit file list instead of the recursive directory scan:

go run ./cmd/distributor manifest create examples/source-bundle \
  --id example-source-bundle \
  --file report.md \
  --file summary.txt \
  --overwrite

Preview Or Publish A Pipeline

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

Use --format json when automation needs structured run results. Use --force only after --dry-run --force reports the intended bounded force_replace action.

Repair Destination State Records

Preview missing managed output records for one configured destination:

go run ./cmd/distributor reconcile-state \
  --config examples/local-publish.yml \
  --pipeline example-source-bundle \
  --destination local-archive \
  --dry-run

Apply the repair after reviewing the report:

go run ./cmd/distributor reconcile-state \
  --config examples/local-publish.yml \
  --pipeline example-source-bundle \
  --destination local-archive

Use --all-owners only when every owner inside the selected catalog root should be repaired.

Prune Managed Outputs

Preview managed outputs selected by the configured retention policy:

go run ./cmd/distributor prune \
  --config examples/local-publish.yml \
  --pipeline example-source-bundle \
  --destination local-archive \
  --dry-run

Apply after reviewing the report:

go run ./cmd/distributor prune \
  --config examples/local-publish.yml \
  --pipeline example-source-bundle \
  --destination local-archive \
  --apply

Use --format json when automation needs structured prune results.

Run HTML And Fan-Out Examples

go run ./cmd/distributor run --config examples/local-html.yml --dry-run
go run ./cmd/distributor run --config examples/local-index.yml --dry-run
go run ./cmd/distributor run --config examples/fan-out.yml --dry-run
go run ./cmd/distributor run --config examples/archive-and-latest.yml --dry-run

These examples exercise implemented output rendering and destination planning behavior. They still use the same run flags and output contract described here.

Start The HTTP Upload Server

go run ./cmd/distributor serve --config examples/http-upload-local.yml

The server exposes health, status, and authenticated upload endpoints according to the loaded configuration. Use Operations for server operation and recovery guidance.

Output And Exit Behavior

Text output is optimized for direct operator use. JSON output is optimized for automation and uses a command-specific result object with a shared envelope similar to:

{
  "schema_version": 1,
  "command": "inspect",
  "ok": true,
  "warnings": [],
  "result": {}
}

• Successful JSON commands emit one JSON document on stdout.
• Usage errors and fatal setup errors exit non-zero and do not emit a JSON result document.
• run --format json emits a JSON result for partial destination failures, sets ok to false, includes result details and errors, and exits non-zero.
• Warnings are included in JSON output and are printed in text output when relevant.
• run summaries include publish_new, upsert_additive, replace_catalog, skip_same, force_replace, fail_unmanaged, and fail_conflict counters. Destination action records use the same stable action values and include the resolved destination_path.

Diagnostics And Recovery

• Use validate before run when checking a bundle supplied by another process.
• Use inspect --format json when automation needs manifest metadata, normalized file details, or checksum information.
• Use run --dry-run before publishing to review destination actions.
• Use reconcile-state --dry-run to inspect missing managed output records before repairing destination state.
• Use prune --dry-run before prune --apply to review configured retention deletes.
• Use Configuration for schema and default details.
• Use Troubleshooting for common errors and corrective action.
• Use Operations for HTTP upload operation, state files, and recovery workflows.