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
distributor run [--config <path>] [--dry-run] [--force]
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`, `ssh`, and `s3` backends.

## 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 output files, destination state, or SSH `known_hosts` entries.
- `--force`: allow explicit destructive replacement for supported conflict cases in this run only.

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

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

Inspect a source bundle:

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

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 a forced replacement before publishing:

```sh
go run ./cmd/distributor run --config <config-path> --dry-run --force
```

## Output

`run` 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 bundle path, destination id, destination backend, action, outputs, and reason. 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.

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

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