Command Reference
dbuild provides a unified CLI for managing the entire image lifecycle.
dbuild analyze
Inspect container image layers, detect zombie layers (cleanup commands that don't reclaim space), scan for leftover compilers, development headers, static libraries, and package caches.
| Flag | Description |
|---|---|
-h, --help |
show this help message and exit |
--variants, --variant |
filter to one or more variants by tag (comma-separated, e.g. pkg,pkg-latest) |
--arch |
override target architecture (e.g. amd64, aarch64) |
--json |
output analysis as JSON |
--threshold-mb |
flag bloat items exceeding this threshold in MB (default: 5.0) |
--skip-container |
skip in-container rootfs audit (layer history analysis only) |
--pull |
pull the image from registry if not found locally in storage |
dbuild appjail-bundle
Render the AppJail files from compose.yaml metadata into a directory -- the same bundle daemonless.io publishes. Emits nothing for images without appjail enabled (meta.appjail unset).
| Flag | Description |
|---|---|
-h, --help |
show this help message and exit |
--out |
output directory (default: ./appjail) |
--image-ref |
override the Makejail 'from' image ref (e.g. a local build for testing) |
dbuild audit
Inspect container image layers, detect zombie layers (cleanup commands that don't reclaim space), scan for leftover compilers, development headers, static libraries, and package caches.
| Flag | Description |
|---|---|
-h, --help |
show this help message and exit |
--variants, --variant |
filter to one or more variants by tag (comma-separated, e.g. pkg,pkg-latest) |
--arch |
override target architecture (e.g. amd64, aarch64) |
--json |
output analysis as JSON |
--threshold-mb |
flag bloat items exceeding this threshold in MB (default: 5.0) |
--skip-container |
skip in-container rootfs audit (layer history analysis only) |
--pull |
pull the image from registry if not found locally in storage |
dbuild baseline
Start a container, wait for it to be ready, and capture a baseline screenshot.
| Flag | Description |
|---|---|
-h, --help |
show this help message and exit |
--variants, --variant |
filter to one or more variants by tag (comma-separated, e.g. pkg,pkg-latest) |
-o, --output |
save screenshot to FILE (default: .daemonless/baseline.png) |
dbuild build
Build container images from Containerfiles.
| Flag | Description |
|---|---|
-h, --help |
show this help message and exit |
--variants, --variant |
filter to one or more variants by tag (comma-separated, e.g. pkg,pkg-latest) |
--arch |
override target architecture (e.g. amd64, aarch64) |
--no-cache |
disable build cache (passes --no-cache to podman build) and ignores cache directories. |
-p, --parallel |
build variants in parallel; optionally limit to N concurrent builds |
--promote-local |
tag directly as the final tag(s) instead of build-{tag}, skipping the staging step normally promoted by dbuild push/dbuild promote. Useful for promoting a build into local final tags without pushing, or so another local Containerfile's FROM can resolve to this image without pulling from the registry. |
--cache-dirs |
Mount a host directory into containers when executing RUN instructions during the build (pased as --volume). If the build.variants.[].cache_dirs parameter is defined, dbuild will use those directories and the ones specified in this parameter as cache directories. |
dbuild choices
The choices resolved for a consumer: per option the env it sets, the services to add or drop, the values to ask for, the defaults and the secrets the extra services need. Empty when the compose declares none.
| Flag | Description |
|---|---|
-h, --help |
show this help message and exit |
--out |
write here instead of stdout |
dbuild ci-prepare
Set up a FreeBSD CI runner with all build dependencies.
| Flag | Description |
|---|---|
-h, --help |
show this help message and exit |
--arch |
override target architecture (e.g. amd64, aarch64) |
--compose |
also install podman-compose |
dbuild ci-run
Run the complete CI/CD pipeline for all (or selected) variants.
| Flag | Description |
|---|---|
-h, --help |
show this help message and exit |
--variants, --variant |
filter to one or more variants by tag (comma-separated, e.g. pkg,pkg-latest) |
--arch |
override target architecture (e.g. amd64, aarch64) |
--prepare |
run ci-prepare before the pipeline |
dbuild ci-test-env
Run read-only checks to verify the CI environment is ready.
| Flag | Description |
|---|---|
-h, --help |
show this help message and exit |
dbuild detect
Auto-detect variants and output the build matrix.
| Flag | Description |
|---|---|
-h, --help |
show this help message and exit |
--format, -f |
output format (default: json) |
dbuild generate
Render documentation and build files using Jinja2 templates.
| Flag | Description |
|---|---|
-h, --help |
show this help message and exit |
--community |
override community help link (e.g. Discord:https://...) |
--check |
don't write; fail if committed README.md/Containerfile* differ from a fresh render (a .j2 was edited without running generate). Checks the current repo, or every subdir from a workspace root. |
dbuild help
Show help for a dbuild subcommand.
| Flag | Description |
|---|---|
-h, --help |
show this help message and exit |
dbuild info
Display detected configuration in a human-readable format.
| Flag | Description |
|---|---|
-h, --help |
show this help message and exit |
dbuild init
Generate starter files for a new dbuild project.
| Flag | Description |
|---|---|
-h, --help |
show this help message and exit |
--freebsd-port |
initialize from a FreeBSD port (e.g. net-p2p/bazarr) |
--flavors |
comma-separated FreeBSD port FLAVORS to scaffold (e.g. lua,wolfssl); crossed with --variants into one tag per combination (e.g. pkg-lua, pkg-wolfssl) |
--name |
application name (e.g. radarr) |
--title |
human-readable title (e.g. Radarr) |
--category |
application category (default: Apps) |
--type |
application type (default: generic) |
--port |
default application port (default: 8080) |
--variants |
comma-separated list of variants to scaffold (default: latest) |
--community |
override community help link (e.g. Discord:https://...) |
--dry-run |
show what would be created without writing to disk |
--github |
generate GitHub Actions workflow (.github/workflows/build.yaml) |
--woodpecker |
generate Woodpecker CI pipeline (.woodpecker.yaml) |
dbuild lint
Check compose.yaml and .daemonless/config.yaml for correctness. Lints the current repo if run from an image directory, or all subdirectories if run from a workspace root.
| Flag | Description |
|---|---|
-h, --help |
show this help message and exit |
dbuild logo
Download or copy an app logo to .daemonless/logo.
| Flag | Description |
|---|---|
-h, --help |
show this help message and exit |
--dark |
save as the dark mode variant (logo-dark. |
dbuild manifest
Create and push multi-architecture manifest lists.
| Flag | Description |
|---|---|
-h, --help |
show this help message and exit |
dbuild promote
Tag already-built build-{tag} images with their final tag, aliases, and version tag. Does not touch the registry or require auth -- run dbuild build (and optionally dbuild test) first.
| Flag | Description |
|---|---|
-h, --help |
show this help message and exit |
--variants, --variant |
filter to one or more variants by tag (comma-separated, e.g. pkg,pkg-latest) |
--arch |
override target architecture (e.g. amd64, aarch64) |
dbuild prune
Find and remove leftover CIT containers (Podman), jails (AppJail), build-tagged images, and /tmp/dbuild-cit-* files for the current project.
| Flag | Description |
|---|---|
-h, --help |
show this help message and exit |
--variants, --variant |
filter to one or more variants by tag (comma-separated, e.g. pkg,pkg-latest) |
-n, --dry-run |
show what would be removed without removing anything |
-y, --force |
do not prompt for confirmation |
dbuild push
Tag and push built images to the configured registry.
| Flag | Description |
|---|---|
-h, --help |
show this help message and exit |
--variants, --variant |
filter to one or more variants by tag (comma-separated, e.g. pkg,pkg-latest) |
--arch |
override target architecture (e.g. amd64, aarch64) |
dbuild sbom
Generate SBOMs (daemonless-native + CycloneDX 1.6 / SPDX 2.3 JSON) via trivy and pkg query.
| Flag | Description |
|---|---|
-h, --help |
show this help message and exit |
--variants, --variant |
filter to one or more variants by tag (comma-separated, e.g. pkg,pkg-latest) |
--arch |
override target architecture (e.g. amd64, aarch64) |
--format |
comma-separated output formats: daemonless, cyclonedx, spdx, all (default: daemonless,cyclonedx) |
--embed |
bake the CycloneDX/SPDX docs into the image at /usr/share/sbom/ (run before push so the pushed image ships them) |
dbuild screenshot
Download one or more upstream images into .daemonless/screenshots/. Uses 'file --mime-type' to detect the real format and SHA-256 to skip duplicates.
| Flag | Description |
|---|---|
-h, --help |
show this help message and exit |
dbuild test
Run container integration tests against built images.
| Flag | Description |
|---|---|
-h, --help |
show this help message and exit |
--variants, --variant |
filter to one or more variants by tag (comma-separated, e.g. pkg,pkg-latest) |
--json |
write test result JSON to FILE |
--backend |
which backend(s) to test with: podman, appjail, or all (default: all) |
--puid |
enable/disable the PUID/PGID re-chown check for this run, overriding the cit: puid: config (e.g. --puid=false). Bare --puid forces it on; default follows config (on). Podman only. |