eric/distributor
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 7 Wiki Activity

Tighten local MVP user documentation

Browse Source
This commit is contained in:
Eric Rakestraw
2026-05-31 04:02:09 +00:00
parent c36217d0df
commit b3044c5b7b
5 changed files with 299 additions and 59 deletions
Download Patch File Download Diff File Expand all files Collapse all files

59
docs/cli.md
View File

@@ -6,44 +6,41 @@
go run ./cmd/distributor run --config examples/local-publish.yml
```
This validates and publishes the example source bundle to `workspace/published/source-bundle`.
This discovers the example source bundle and publishes source files to `workspace/published/source-bundle`.
## Command overview
```sh
distributor --help
distributor [--help]
distributor version
distributor run
distributor validate
distributor inspect
distributor run [--config <path>] [--dry-run]
distributor validate <path>
distributor inspect <path>
```
`version` prints the application name and version. The default development version is `dev`; release builds may replace it at build time.
- `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.
`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.
`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
The root command supports:
Root command:
- `--help`, `-h`: print root help.
- `--help`, `-h`, or `help`: print root help.
Each subcommand supports:
All subcommands:
- `--help`, `-h`: print command-specific help.
`run` supports:
`run` flags:
- `--config <path>`: config file to load.
- `--dry-run`: validate config, print planned actions and final status, and do not publish.
- `--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
@@ -65,7 +62,7 @@ Preview local publication without writing:
go run ./cmd/distributor run --config examples/local-publish.yml --dry-run
```
Publish the local example:
Publish the local source example:
```sh
go run ./cmd/distributor run --config examples/local-publish.yml
@@ -76,3 +73,21 @@ 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).