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](config.md), operational recovery guidance lives in [Operations](operations.md), failure diagnosis lives in [Troubleshooting](troubleshooting.md), and external contracts live under [Integrations](integrations/source-bundle.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 <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`

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

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

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

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

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

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

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

```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 <path>` 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 after `--dry-run --force` reports the intended bounded `force_replace` action.

### Repair Destination State Records

Preview missing managed output records for one configured destination:

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

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

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

Apply after reviewing the report:

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

```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.
- `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](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.