94 lines
3.2 KiB
Markdown
94 lines
3.2 KiB
Markdown
# 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]
|
|
distributor validate <path>
|
|
distributor inspect <path>
|
|
```
|
|
|
|
- `version`: prints the application name and version. Development builds print `distributor dev`.
|
|
- `run`: loads a YAML config, discovers local 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` currently executes local backends only. SSH and S3 config can be parsed and validated, but configured SSH or S3 execution fails with a clear unsupported-execution error.
|
|
|
|
## 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 files.
|
|
|
|
`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
|
|
```
|
|
|
|
## Output
|
|
|
|
`run` prints the number of configured pipelines, one line per pipeline, one line per planned destination action, and a final status line. Actions include:
|
|
|
|
- `publish_new`: destination has no managed state and is empty.
|
|
- `replace_older`: destination state is older than the source manifest.
|
|
- `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.
|
|
|
|
## 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).
|