Use the CLI

ContainerHive's behavior can be controlled with various commands and flags.

You can get a full list by running

ch --help

Global Flags

Flag	Description
`--project`, `-p`	Project root directory
`--build-id`	Build ID appended to tags as `+<id>`
`--log-level`	Log level (`debug`, `info`, `warn`, `error`) — sourced from `LOG_LEVEL` env (default: `info`)
`--generate`, `-g`	Run `ch generate` before the command

Commands

`generate`

Discover project and render configurations to dist/.

ch generate

This must run before build. It parses hive.yml and all image definitions.

`build`

Build container images with BuildKit.

ch build [image:tag patterns...]

Flag	Description
`--registry`	Use registry from config (auto-enabled in CI)
`--platform`	Target platform(s) to build (e.g. `linux/amd64`), overrides `hive.yml`

You can filter which images to build by passing image:tag patterns as arguments. In CI environments, the registry is auto-enabled.

`test`

Run container structure tests on built images.

ch test [image:tag patterns...]

Flag	Description
`--build`	Run build before tests

You can combine --build with --generate to run the full pipeline in one command:

ch test --generate --build

Uses container-structure-test to validate built images against test definitions.

`sbom`

Generate Software Bill of Materials for built images.

ch sbom [image:tag patterns...]

Flag	Description
`--platform`	Target platform(s) to generate SBOMs for (e.g. `linux/amd64`), overrides `hive.yml`
`--workers`	Number of concurrent workers for SBOM generation (default: 4)

Generates CycloneDX JSON format SBOMs using Syft as a Go library. No external tooling required.

`finalize`

Create multi-arch manifests and semantic version alias tags in the registry.

ch finalize [image:tag patterns...]

Creates manifests from platform-specific images and applies semantic version alias tagging. Requires a running registry.

`verify`

Verify project structure.

ch verify

Validates hive.yml and image definitions. Useful as a quick check before building.

`lint`

Lint Dockerfiles in the project with hadolint. The hadolint binary is embedded in ch — no separate install required.

ch lint

Flag	Description
`--failure-threshold`	Lowest severity that causes a non-zero exit (`error`, `warning`, `info`, `style`, `ignore`). Overrides `lint.failure_threshold` from `hive.yml`. Defaults to `error`.
`--codeclimate-report`	Path to write a GitLab Code Quality JSON report (Code Climate format). Written even when the command exits non-zero.

Findings are printed to stdout in path:line:column level code: message format. Templated Dockerfiles (files with a templating extension such as Dockerfile.gotpl) are skipped — hadolint cannot parse Go template syntax — and a warning is logged for each skipped file. Per-variant Dockerfiles are linted alongside the parent image.

Configure hadolint behaviour with a lint: block in hive.yml. See Hive configuration.

GitLab Code Quality integration

--codeclimate-report gl-code-quality-report.json writes a Code Climate–compatible JSON report that GitLab CI can render inline on merge requests. Severities are mapped from hadolint to Code Climate as follows:

hadolint	Code Climate
`error`	`blocker`
`warning`	`major`
`info`	`minor`
`style`	`info`

Wire it into .gitlab-ci.yml like any other code-quality artifact:

lint:
  script:
    - ch lint --codeclimate-report gl-code-quality-report.json
  artifacts:
    when: always
    reports:
      codequality: gl-code-quality-report.json

Every parsed finding lands in the report — even ones below the failure threshold — so GitLab surfaces the full picture while the command's exit code still reflects the threshold.

`template ci`

Generate CI pipeline configuration.

ch template ci --provider <provider> --output <path>

Flag	Description
`--provider`	CI provider (`gitlab` or `github`)
`--output`	Output file (default: stdout)
`--template-dir`	Custom template directory (overrides built-in templates)
`--artifacts`	Upload/download build artifacts between jobs
`--version`	CH CLI version to use in CI templates (default: current CLI version)
`--image-name`	Container image name for the CH CLI (default: `containerhive/containerhive`)

`template custom`

Render custom Go templates with project context.

ch template custom --template <path.gotpl> --output <path>

Flag	Description
`--template`	Path to Go template file (`.gotpl`)
`--output`	Output file (default: stdout)

`wait`

Wait for infrastructure dependencies to become available.

ch wait

Flag	Description
`--buildkitd`	Wait for BuildKit daemon (uses `$BUILDKIT_HOST`, default `tcp://127.0.0.1:8372`)
`--docker-socket`	Wait for Docker daemon (uses `$DOCKER_HOST`, default `unix:///var/run/docker.sock`)
`--timeout`	Maximum time to wait (default: 1m)

`login`

Log in to a container registry.

ch login <registry> -u <username> -p <password>

Flag	Description
`--username`, `-u`	Username
`--password`, `-p`	Password
`--password-stdin`	Take the password from stdin

`dev buildkitd`

Manage a local BuildKit daemon container for development. See Local development for full details.

ch dev buildkitd start
ch dev buildkitd stop
ch dev buildkitd status
ch dev buildkitd logs

start flags:

Flag	Description
`--image`	BuildKit image to use (`image:tag`). Defaults to the version configured in `hive.yml` `template_options` or the bundled version
`--port`	Host port to bind
`--timeout`	Maximum time to wait for buildkitd to become ready (default: 1m)

stop flags:

Flag	Description
`--remove`	Also remove the container after stopping

logs flags:

Flag	Description
`--follow`, `-f`	Follow log output

`report`

Generate an HTML or JSON report of container images.

ch report

Flag	Description
`--output`	Output file path (default: `dist/report.html`)
`--json`	Output JSON instead of HTML

Generates a report containing information about all configured images, including their build status, dependencies, and metadata.

`license`

Show third-party license notices.

ch license

`mcp`

Start a Model Context Protocol (MCP) server for AI tool integration.

ch mcp

See MCP integration for full details.