distributor/docs/cli.md

# Distributor CLI

## Shortest useful command

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

This validates and publishes the example source bundle to `workspace/published/source-bundle`.

## Command overview

```sh
distributor --help
distributor version
distributor run
distributor validate
distributor inspect
```

`version` prints the application name and version. The default development version is `dev`; release builds may replace it at build time.

`run --config <path>` executes configured local-to-local pipelines that publish source files, generated HTML files, or both.

`run --config <path> --dry-run` discovers source bundles, inspects destination state, and prints planned actions plus a final status summary without writing files.

`validate <path>` validates a local source bundle directory or a local tree containing source bundles.

`inspect <path>` validates discovered local source bundles and prints a concise normalized summary.

Remote backends are not implemented yet.

## Flag reference

The root command supports:

- `--help`, `-h`: print root help.

Each subcommand supports:

- `--help`, `-h`: print command-specific help.

`run` supports:

- `--config <path>`: config file to load.
- `--dry-run`: validate config, print planned actions and final status, and do not publish.

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