Air-Gap CLI Command Reference

Purpose: For operators, provides every air-gap CLI command with flags, options, and examples.

Overview

The opencenter-airgap CLI manages the full build lifecycle for air-gap packages. All commands operate relative to the project root directory.

Package: opencenter-build (Python, version 1.0.0-rc2)

Commands

init

Initialize a new build environment.

opencenter-airgap init [--template baremetal|openstack]

Flag	Default	Description
--template	baremetal	Template type; openstack includes Terraform provider config

Creates config/versions.env with default version pins. Safe to run in an existing project — does not overwrite existing files.

add

Add a component to the manifest.

opencenter-airgap add image <image-reference>
opencenter-airgap add tool --name <name> --version <version> --url <url>
opencenter-airgap add repo <git-url>
opencenter-airgap add chart <chart-reference>

Subcommands:

Subcommand	Required args	Description
image	<image-ref> (must include tag)	Add a container image
tool	--name, --version, --url	Add a CLI binary or tool
repo	<git-url>	Add a Git repository for scanning
chart	<chart-ref>	Add a Helm chart

Appends to config/components.yaml. Duplicates are detected and skipped.

scan

Discover container images and Helm charts from repositories.

opencenter-airgap scan --repos
opencenter-airgap scan --repo <path>

Flag	Description
--repos	Clone and scan all repositories from versions.env
--repo <path>	Scan a specific local directory

Parses YAML files for image: fields and HelmRelease/HelmRepository resources. Results merge into components.yaml.

generate-manifest

Generate zarf.yaml from the current manifest.

opencenter-airgap generate-manifest

Renders zarf.yaml.template with variables from versions.env and components.yaml. This is also run automatically as part of build, but can be invoked independently to inspect the generated Zarf definition.

build

Build the air-gap package.

opencenter-airgap build [--clean] [--resume] [--force-regenerate]

Flag	Description
--clean	Remove previous build artifacts before starting
--resume	Resume from last successful checkpoint
--force-regenerate	Regenerate components.yaml from versions.env (discards manual edits)

Executes all 8 build phases:

1. scan_repositories — Clone repos, scan for image references
2. collect_helm_charts — Find and pull Helm charts
3. generate_kubespray_lists — Generate Kubespray file/image lists
4. mirror_terraform_providers — Build Terraform filesystem mirror
5. organize_assets — Download all binaries, images, packages
6. generate_zarf_yaml — Render Zarf definition
7. create_zarf_package — Package into .tar.zst with SBOM
8. generate_manifest — Write artifact-manifest.json with checksums

Every step writes a checkpoint to build/state.json for resume on failure.

validate

Validate configuration and manifest.

opencenter-airgap validate

Checks:

• versions.env syntax and required variables
• components.yaml schema compliance
• URL reachability for declared artifacts (Zone A only)
• zarf.yaml component references match collected assets

verify

Verify a built package.

opencenter-airgap verify <package-path> [--manifest <manifest-path>]

Flag	Description
--manifest	Path to artifact-manifest.json (auto-detected if omitted)

Checks archive integrity, component completeness, SBOM presence, and Cosign signature.

status

Display build status and artifact counts.

opencenter-airgap status

Shows each build phase with state (complete/pending/failed), artifact counts, and timestamps.

clean

Remove build artifacts and state.

opencenter-airgap clean

Deletes build/, dist/, and state file. Preserves config/versions.env and config/components.yaml.

serve

Deploy a package and start bastion services.

opencenter-airgap serve <PACKAGE>

Extracts the specified Zarf package and starts:

• Container registry (serves OCI images)
• Nginx file server (OS packages, Python wheels, K8s binaries)

Includes health check endpoints. Used for testing locally before physical transfer, or for deploying on the Zone C bastion.

keygen

Generate signing keys.

opencenter-airgap keygen

Creates a Cosign key pair for artifact signing. Keys stored in .secrets/ directory.

release

Create a release artifact with metadata.

opencenter-airgap release [VERSION]

Tags the current build with the specified version, produces the final distributable package with version metadata, checksums, and signatures. If VERSION is omitted, uses the version from pyproject.toml.

version

Display CLI version.

opencenter-airgap version

Exit Codes

Code	Meaning
0	Success
1	General error (check stderr for details)
2	Invalid arguments or missing required flags

Environment Variables

The CLI reads config/versions.env for build configuration. It does not use shell environment variables for version pinning — all configuration is file-based.

Installation

# From source (development)
pip install -e ".[dev]"

# Production
pip install opencenter-build

Requires Python 3.12+.