223 lines
9.1 KiB
Markdown
223 lines
9.1 KiB
Markdown
# 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 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.
|
|
- `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`, `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 a run when destination state indicates a conservative safety check would otherwise block it.
|
|
- `--format text|json` selects human-readable or machine-readable output.
|
|
|
|
`run` accepts no positional arguments.
|
|
|
|
### `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 when the operator has reviewed the destination state conflict and intentionally wants to continue.
|
|
|
|
### 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.
|
|
|
|
## 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 [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.
|