distributor/docs/cli.md

# Distributor CLI

## Shortest useful command

```sh
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

```sh
distributor [--help]
distributor version [--format text|json]
distributor run [--config <path>] [--dry-run] [--force] [--format text|json]
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.
- `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 sources and destinations.

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

`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:

```sh
go run ./cmd/distributor validate examples/source-bundle
```

Inspect a source bundle:

```sh
go run ./cmd/distributor inspect examples/source-bundle
```

Validate a configured source without opening destinations:

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

Inspect one configured source bundle:

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

Create a manifest for a local producer bundle:

```sh
go run ./cmd/distributor manifest create <bundle-path> --id <bundle-id>
```

Create a manifest with explicit file order:

```sh
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:

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

Publish the local source example:

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

Publish the local HTML example:

```sh
go run ./cmd/distributor run --config examples/local-html.yml
```

Preview local fan-out publication:

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

Preview local archive-plus-latest publication:

```sh
go run ./cmd/distributor run --config examples/archive-and-latest.yml --dry-run
```

Preview a forced replacement before publishing:

```sh
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:

```json
{
  "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](troubleshooting.md). For destination state and retry behavior, see [operations](operations.md). For config fields and defaults, see [configuration](config.md).