# 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](config.md), operational recovery guidance lives in [Operations](operations.md), and failure diagnosis lives in [Troubleshooting](troubleshooting.md). ## Shortest Useful Command Run the maintained local publishing example from the repository root: ```sh 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 ```text distributor [--help] distributor help distributor version [--format text|json] distributor run [--config ] [--dry-run] [--force] [--format text|json] distributor serve [--config ] distributor validate [--format text|json] distributor validate --config --pipeline [--bundle ] [--format text|json] distributor inspect [--format text|json] distributor inspect --config --pipeline [--bundle ] [--format text|json] distributor manifest distributor manifest create --id [options] distributor manifest create --id [options] ``` - `version` prints the application name and version. - `run` executes configured pipelines against their destinations. - `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`, `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` ```sh 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` ```sh distributor run [--config ] [--dry-run] [--force] [--format text|json] ``` - `--config ` 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 a run when destination state indicates a conservative safety check would otherwise block it. - `--format text|json` selects human-readable or machine-readable output. `run` accepts no positional arguments. ### `serve` ```sh distributor serve [--config ] ``` - `--config ` 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` ```sh distributor validate [--format text|json] distributor validate --config --pipeline [--bundle ] [--format text|json] ``` `validate` has two source modes: - Local path mode validates the bundle at ``. - Configured source mode resolves the source from `--config ` and `--pipeline `. Configured source flags: - `--config ` loads the configuration file. - `--pipeline ` selects the configured pipeline source to validate. - `--bundle ` 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` ```sh distributor inspect [--format text|json] distributor inspect --config --pipeline [--bundle ] [--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` ```sh distributor manifest create --id [options] distributor manifest create --id [options] ``` Flags may appear before or after the bundle path. Both `--flag value` and `--flag=value` forms are accepted. - `--id ` sets the manifest bundle identifier and is required. - `--created ` sets the manifest creation timestamp. If omitted, the current UTC time is used. - `--file ` 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 ```sh go run ./cmd/distributor validate examples/source-bundle go run ./cmd/distributor inspect --format json examples/source-bundle ``` ### Validate Or Inspect A Configured Source ```sh 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 ` with configured source mode when automation needs to validate or inspect an alternate bundle path through the selected pipeline configuration. ### Create A Manifest ```sh 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: ```sh 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 ```sh 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 when the operator has reviewed the destination state conflict and intentionally wants to continue. ### Run HTML And Fan-Out Examples ```sh 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 ```sh 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](operations.md) 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: ```json { "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. ## 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 [Configuration](config.md) for schema and default details. - Use [Troubleshooting](troubleshooting.md) for common errors and corrective action. - Use [Operations](operations.md) for HTTP upload operation, state files, and recovery workflows.