Initialize project configuration.

| Flag | Default | Purpose | |---|---|---| | --template | baremetal | Template for versions.env. openstack adds Terraform-OpenStack defaults. | | --config | config/versions.env | Where to write versions.env. |

Creates config/, config/schemas/, build/, dist/, and assets/. Writes a default versions.env. Does not create components.yaml — build does that on first run.

If config/versions.env already exists, the command prompts before overwriting.

Add a component to config/components.yaml. Creates the manifest if it does not exist.

TYPE is one of tool, repo, image, chart.

| Flag | Required for | Purpose | |---|---|---| | --version | tools, charts | Component version (no leading v required). | | --url | tools, repos | Tool download URL or Git clone URL. May contain {{version}}. | | --ref | repos | Git ref (branch, tag, or commit SHA). | | --repo | charts | Helm or Git repo URL the chart lives in. | | --extract | tools (optional) | Extract the downloaded archive. | | --binary | tools with --extract | Path to the binary inside the archive. | | --manifest | (optional) | Manifest path. Defaults to config/components.yaml. |

Examples:

Discover container images and Helm charts in Git repositories. Updates config/components.yaml and writes the discovered images, Helm repositories, and Helm releases to plain-text files under config/.

| Flag | Default | Purpose | |---|---|---| | --repos | off | Clone the repositories listed in versions.env into build/ before scanning. | | --repo PATH | (none) | Scan a specific directory. May be repeated. | | --discover-images | off | Read repo paths from config/components.yaml. | | --concurrency N | auto | Worker processes for the scan. | | --output | config/all-images.txt | Output file for the deduplicated image list. | | --verbose | off | Print per-repo image counts and the first 5 entries of each result set. |

Outputs:

Generate zarf.yaml from the component manifest.

| Flag | Default | Purpose | |---|---|---| | --output | zarf.yaml | Output path for the generated Zarf manifest. | | --components | config/components.yaml | Component manifest to read. | | --config | config/versions.env | Configuration to read. | | --validate / --no-validate | --validate | Run a basic YAML and required-fields check after generation. |

Used internally by build. Run it directly if you want to inspect the generated zarf.yaml without running the full build.

Run the full build pipeline.

| Flag | Default | Purpose | |---|---|---| | --clean | off | Delete build/state.json before running. Wipes the checkpoint. | | --resume / --no-resume | --resume | Skip steps already marked completed in build/state.json. | | --force-regenerate | off | Rebuild config/components.yaml from versions.env. Manual edits are still merged in. | | --config | config/versions.env | Configuration file. | | --state | build/state.json | Checkpoint file. | | --verbose | off | Print full tracebacks on failure. |

Behavior:

Run schema validation on versions.env and components.yaml.

| Flag | Default | Purpose | |---|---|---| | --strict | off | Treat warnings as errors. | | --check-upstream | off | Reserved — not implemented yet. Prints a warning. | | --config | config/versions.env | Configuration file. | | --components | config/components.yaml | Component manifest. |

Returns non-zero on any error (or any warning when --strict). The validator is src/opencenter_build/validation.py:ComprehensiveConfigValidator.

Verify a built package.

| Argument / Flag | Purpose | |---|---| | PACKAGE | Path to the .tar.zst package. | | --manifest | Optional artifact manifest (dist/artifact-manifest.json) to cross-check against. |

Prints a table of: signature valid, checksums valid, manifest matches (if provided), artifact count. Exit code is non-zero on any failure.

The CLI does not check SBOM policy. Use hack/scripts/verify-package.sh for that. See ../operations/verify-package.md[Verify a Built Package].

Show build state.

| Flag | Default | Purpose | |---|---|---| | --state | build/state.json | State file location. |

Prints build ID, start time, config hash, and a per-step table with status (Completed / Failed / Running / Pending), duration, and truncated error message. Also lists known build artifacts (zarf.yaml, dist/artifact-manifest.json, dist/zarf-package-*.tar.zst) when the build is complete.

Remove build artifacts.

| Flag | Default | Purpose | |---|---|---| | --state | build/state.json | State file to remove. | | --build-dir | build | Build directory to remove. | | --dist-dir | dist | Distribution directory to remove. | | --yes, -y | off | Skip the confirmation prompt. |

Lists each item with a file count and prompts before deletion unless --yes is passed.

Deploy a Zarf package on the bastion and start the bastion services.

| Flag | Default | Purpose | |---|---|---| | --verify / --no-verify | --verify | Run verify on the package before deploying. | | --nginx-port | 80 | Port for the nginx file server. | | --registry-port | 31999 | Port for the container registry. | | --git-port | 3000 | Port for the Gitea server. | | --install-path | /opt/opencenter | Bastion install directory. | | --verbose | off | Print Zarf and Docker stdout/stderr. |

After zarf package deploy, starts an nginx:1.29.2 container with mounts for /files, /debs, and /pypi, then runs HTTP health checks on every service. Cleans up the nginx container on failure.

Requires the Zarf CLI and Docker on the bastion’s $PATH.

Print versions.

Prints the package version and a table of Python plus key dependency versions (typer, rich, pyyaml, hypothesis, jsonschema).

Generate a Cosign signing keypair.

| Flag | Default | Purpose | |---|---|---| | --output, -o | .secrets | Directory for the keys. | | --name, -n | signing-key | Filename stem. The output is <name>.key (private) and <name>.pub (public). | | --force, -f | off | Overwrite existing keys. |

Prompts for a password (minimum 8 characters), shells out to cosign generate-key-pair, sets 0600 on the private key, and adds the output directory to .gitignore if a git repo is detected.

Requires cosign on $PATH.

Tag the current commit and push to trigger a CI/CD release.

| Argument / Flag | Default | Purpose | |---|---|---| | VERSION | (read from pyproject.toml) | Version to tag, with or without leading v. | | --dry-run | off | Print the commands that would run, but do not tag or push. | | --force | off | Skip the confirmation prompt. |

Refuses to run with a dirty working tree, missing origin remote, or an existing tag. Creates an annotated tag with message Release vX.Y.Z and pushes it to origin.