CLI reference

The executable is named debark. Use debark COMMAND --help to check the options available in your installed version.

Examples below use target.snapshot.tar.zst and the signing keys operator.key / operator.pub. The quick start walks through creating them.

Common starting points

Use guided questions for the target, packages, and build options:

debark build --interactive

Build directly for a baseline OS, without a captured snapshot:

debark build --base ubuntu:24.04/minimal --arch amd64 \
  --out ./bundle --sign operator.key jq

To choose and save a reusable baseline through prompts:

debark snapshot from-base --interactive

See Use the interactive CLI for the prompts and saved package list, or Build with a baseline OS for a baseline walkthrough. See supported systems for exact baseline IDs and values for --arch.

Command index

Command	Purpose
snapshot create	Capture a machine’s package state.
snapshot inspect	Read a snapshot.
snapshot from-base	Create a snapshot for a stock release.
snapshot list-bases	List available stock bases.
build	Download packages and assemble a bundle.
verify	Check a bundle’s signature and files.
install	Verify and install a bundle.
inspect	Show a bundle’s contents.
doctor	Check for common offline installation issues.
store ls	List cached downloads.
store gc	Remove unused cached downloads.
config init	Create a configuration file.
config show	Show loaded settings.
config path	Show the selected configuration path.
version	Print version and build information.
keygen	Generate a signing key pair.

Global flags

These options are accepted by all commands. Whether a command writes JSON or events is described in JSON output.

Option	Default	Description
--json	Off	Print the command’s JSON result.
--json-events PATH	Unset	Write one JSON event per line to a file. Use - for stdout.
--no-color	Off	Disable colored output. Also honors NO_COLOR and TERM=dumb.
--config PATH	Platform config path	Read configuration from this path.
--profile NAME	No profile	Apply a named configuration profile.
--help, -h	—	Show command help.

JSON modes disable prompts and terminal progress. They cannot be combined with --interactive. If you want both a JSON result and an event stream, send events to a file.

Other options use their full names: for example, --out and --yes. Get version information with the version subcommand.

debark snapshot

Run debark snapshot --help to list snapshot commands.

debark snapshot create

Capture apt and dpkg state on the target machine. No positional arguments or root access are required.

debark snapshot create --out target.snapshot.tar.zst

Option	Default	Description
--out PATH	snapshot.tar.zst	Output snapshot archive.
--redact	Off	Remove machine ID, proxy settings, and labels.
--no-keyrings	Off	Omit captured repository keys. The build loses those keys and Signed-By pins; approved-key checks cannot pass without that material.
--label KEY=VALUE	None	Attach a label. Repeat for multiple labels.

Use --label site=office to attach a label, or --redact to remove identifying fields. Labels are removed by redaction.

debark snapshot inspect

debark snapshot inspect target.snapshot.tar.zst

Takes one snapshot path and no command-specific options. Shows the target and whether the snapshot was captured from a machine or synthesized from a base. With --json, prints the full snapshot document.

debark snapshot from-base

debark snapshot from-base ubuntu:24.04/server --arch amd64

Takes a built-in base ID or a base definition file. Use this when you cannot capture the target; it assumes a stock installed package set.

Option	Default	Description
--out PATH	Derived from base and architecture	Output snapshot archive.
--arch ARCH	This machine’s architecture	Architecture of the intended target.
--backend NAME	Configured value, else auto	Choose auto, local, or container.
--image IMAGE	Configured value or target default	Container image override.
--self-binary PATH	Configured value or auto-detection	Linux Debark binary to run inside the container.
--interactive	Off	Prompt for missing choices. Requires a terminal.

The example writes ubuntu-24.04-server-amd64.snapshot.tar.zst unless --out is supplied. Windows and macOS builders need a suitable Linux helper for container execution; see Build backends.

debark snapshot list-bases

debark snapshot list-bases --arch amd64

Lists the bases included in your installed binary. The optional --arch ARCH selects the target architecture; it defaults to this machine’s architecture.

Base IDs include a distribution, version, and variant, such as ubuntu:24.04/server. Omitting the variant selects minimal. See Build without a target machine.

debark build

debark build --snapshot target.snapshot.tar.zst \
  --out ./bundle --sign operator.key jq tree

Takes package names, name=version requests, HTTPS URLs to .deb files, local .deb paths, or a mixture. Use --list for inputs in a text file.

Target and inputs

Option	Default	Description
--snapshot FILE	Unset	Snapshot describing the target machine.
--base BASE	Unset	Stock base ID or base definition file, instead of a snapshot.
--arch ARCH	This machine’s architecture	Architecture for --base. Cannot be used with --snapshot.
--list FILE	None	Input list file. Repeat for multiple lists.
--local-dir DIR	None	Read .deb files from this directory, without subdirectories. Repeatable.
--digest URL=SHA256	None	Expected SHA-256 checksum for a URL input. Repeatable.
--interactive	Off	Prompt for missing choices and print the equivalent command. Requires a terminal.

Supply --snapshot, --base, or --interactive. Do not combine --snapshot and --base.

Output and package selection

Option	Default	Description
--out DIR	./bundle	Write a bundle folder.
--tar NAME	Unset	Write NAME.debark.tar.zst instead of a folder.
--update	Off	Refresh indexes, resolve again, and prune superseded files.
--no-prune	Off	Keep superseded files during an update.
--upgrades	Off	Include a full-upgrade pass for packages installed on the target.
--recommends	Follow target settings	Include recommended packages.
--no-recommends	Follow target settings	Exclude recommended packages.
--sbom	Off	Add a CycloneDX SBOM at sbom.cdx.json.
--embed-binary PATH	Unset	Copy a target Linux executable to bin/debark-linux-ARCH.

Do not combine --out with --tar, or --recommends with --no-recommends. --update does not imply --upgrades. See Upgrade installed packages.

Backend and signing

Option	Default	Description
--backend NAME	Configured value, else auto	Choose auto, local, or container.
--image IMAGE	Configured value or target default	Container image override.
--self-binary PATH	Configured value or auto-detection	Linux executable used inside the build container.
--sign KEY	Configured sign_key, if available	Private key file, gpg:KEY_ID, or plugin:NAME. An explicit flag makes signing required.
--no-sign	Off	Write an unsigned bundle.
--approved-keys FILE	Configured approved_keys_file	Allowed archive signing key fingerprints.
--policy FILE	Configured policy_file	Policy evaluated against the package plan.
--acknowledge-redistribution	Off	Skip the redistribution confirmation prompt; warnings remain recorded.

Do not combine --sign and --no-sign. Without either flag, a configured signing key is used without making signing required. Use an explicit --sign when a successful build must be signed.

Set the cache path with store_dir or DEBARK_STORE. Set the container runtime with container_runtime or DEBARK_CONTAINER_RUNTIME; these are configuration settings.

Exit code 3 means an incomplete bundle, 5 means resolution failed, and 6 means policy rejected the build. Other errors use the common exit codes.

debark verify

debark verify ./bundle --key operator.pub

Takes a bundle folder or archive. Checks signatures, file contents, and metadata without installing packages.

Option	Default	Description
--key FILE	Configured verify_keys	Public verification key. Repeat for multiple files.
--keyring DIR	Configured verify_keyring_dirs	Directory of trusted public keys. Repeat for multiple directories.
--gpg-keyring FILE	GPG’s default keyring	GPG keyring containing the expected signer’s public key.
--allow-unsigned	Off	Allow a bundle without a valid trusted signature. File checks still apply.

Verification failures return exit code 4. Keys inside the bundle folder are refused. Read Verify a bundle for report fields and common failures.

debark install

Preview, then apply on the target:

debark install ./bundle --key operator.pub --status
sudo debark install ./bundle --key operator.pub --yes

Takes a bundle folder or archive. Installation verifies it first and uses the exact versions in the lock.

Option	Default	Description
--status	Off	Report the installation plan without applying it.
--dry-run	Off	Preview the installation without applying it.
--upgrade	Off	Also request the lock’s upgrade set.
--all	Off	Request every package recorded in the bundle.
--yes	Off	Accept apt prompts. Required for unattended installation.
--keep-source	Off	Keep a permanent Trusted: yes apt source. Later apt commands use it without Debark verification.
--fast	Off	Use noninteractive debconf and --force-unsafe-io, reducing crash durability.
--dpkg	Off	Bypass apt and run dpkg unpack/configure steps directly.
--key FILE	Configured verify_keys	Public verification key. Repeat for multiple files.
--keyring DIR	Configured verify_keyring_dirs	Directory of trusted public keys. Repeat for multiple directories.
--gpg-keyring FILE	GPG’s default keyring	GPG keyring containing the expected signer’s public key.
--allow-unsigned	Off	Allow a bundle without a valid trusted signature. File checks still apply.

--status and --dry-run are mutually exclusive. Review upgrades, removals, and release warnings before applying a plan.

An architecture mismatch stops installation with exit code 7. A release mismatch warns. See Install a bundle for prerequisites and advanced options.

debark inspect

debark inspect ./bundle

Takes one bundle folder or archive, with no command-specific options. Shows the target, packages, sizes, and warnings. It reads the metadata without verifying file contents or signatures.

With --json, returns schema_version, bundle_path, signed, manifest, and lock.

debark doctor

debark doctor ./bundle
debark doctor --snapshot target.snapshot.tar.zst

Supply exactly one bundle argument or --snapshot FILE.

Option	Default	Description
--snapshot FILE	Unset	Check this snapshot instead of a bundle.
--no-scan-scripts	Off	Skip extracting and scanning package maintainer scripts.

Checks for common offline installation issues and reports notes or warnings. A completed scan exits 0 even when it has findings. Errors reading or scanning the input can still fail the command.

See Policy and package checks for the checks and how to act on them.

debark store

The store is a cache of downloaded packages. It is shared across builds.

debark store ls

debark store ls

No positional arguments. Lists cached packages and sizes. --store DIR selects another cache; otherwise the configured or platform default is used.

debark store gc

debark store gc ./bundle --dry-run

Takes zero or more bundle paths. Keeps cached files referenced by those bundles and files marked user-supplied; removes the remaining cached objects.

Option	Default	Description
--store DIR	Configured or platform cache path	Cache to clean.
--dry-run	Off	Show what would be removed without deleting anything.

With no bundle arguments, only user-supplied objects are protected. This removes cached copies; existing bundle files remain usable. See Download cache and cleanup.

debark config

Configuration lists file locations, settings, profiles, and environment variables.

debark config init

debark config init

Creates a starter configuration. No positional arguments. --force replaces an existing file; without it, the command refuses to overwrite one.

Always prints plain text, including with --json.

debark config show

debark config show --json

No positional arguments or command-specific options. Prints the effective configuration for the selected file, profile, and environment.

debark config path

debark config path

No positional arguments or command-specific options. Prints the chosen configuration path, whether or not it exists. Always prints plain text.

debark version

debark version

No positional arguments or command-specific options. Prints version and build details. With --json, returns a JSON object with version, edition, platform, Go version, and available build metadata.

debark keygen

debark keygen --out operator.key --comment "Package bundles"

Generates an Ed25519 signing key pair. No positional arguments.

Option	Default	Description
--out PATH	Required	Private key output path.
--comment TEXT	Empty	Comment stored with the key.

The private key is unencrypted. A .key suffix is replaced with .pub for the public file; otherwise .pub is appended. Keep the private key secure and provide only the public key to targets.

See Sign a bundle for the full workflow.