# CLI reference Commands, options, and defaults for the debark command-line tool. Source: https://debark.dev/docs/reference/cli --- 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](/docs/get-started/quickstart) walks through creating them. ## Common starting points Use guided questions for the target, packages, and build options: ```bash debark build --interactive ``` Build directly for a baseline OS, without a captured snapshot: ```bash debark build --base ubuntu:24.04/minimal --arch amd64 \ --out ./bundle --sign operator.key jq ``` To choose and save a reusable baseline through prompts: ```bash debark snapshot from-base --interactive ``` See [Use the interactive CLI](/docs/get-started/interactive) for the prompts and saved package list, or [Build with a baseline OS](/docs/get-started/no-target-machine) for a baseline walkthrough. See [supported systems](/docs/get-started/supported-systems#baseline-os-list) for exact baseline IDs and values for `--arch`. ## Command index | Command | Purpose | | ---------------------------------------------------- | --------------------------------------------- | | [snapshot create](#debark-snapshot-create) | Capture a machine’s package state. | | [snapshot inspect](#debark-snapshot-inspect) | Read a snapshot. | | [snapshot from-base](#debark-snapshot-from-base) | Create a snapshot for a stock release. | | [snapshot list-bases](#debark-snapshot-list-bases) | List available stock bases. | | [build](#debark-build) | Download packages and assemble a bundle. | | [verify](#debark-verify) | Check a bundle’s signature and files. | | [install](#debark-install) | Verify and install a bundle. | | [inspect](#debark-inspect) | Show a bundle’s contents. | | [doctor](#debark-doctor) | Check for common offline installation issues. | | [store ls](#debark-store-ls) | List cached downloads. | | [store gc](#debark-store-gc) | Remove unused cached downloads. | | [config init](#debark-config-init) | Create a configuration file. | | [config show](#debark-config-show) | Show loaded settings. | | [config path](#debark-config-path) | Show the selected configuration path. | | [version](#debark-version) | Print version and build information. | | [keygen](#debark-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](/docs/reference/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. ```bash 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 ```bash 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 ```bash 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](/docs/concepts/backends). ### debark snapshot list-bases ```bash 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](/docs/get-started/no-target-machine). ## debark build ```bash 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](/docs/guides/upgrades). ### 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](/docs/reference/configuration). 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](/docs/reference/exit-codes). ## debark verify ```bash 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](/docs/trust/verifying) for report fields and common failures. ## debark install Preview, then apply on the target: ```bash 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](/docs/operate/installing) for prerequisites and advanced options. ## debark inspect ```bash 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 ```bash 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](/docs/guides/policy-and-doctor) 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 ```bash 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 ```bash 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](/docs/concepts/store-and-incremental). ## debark config [Configuration](/docs/reference/configuration) lists file locations, settings, profiles, and environment variables. ### debark config init ```bash 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 ```bash 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 ```bash 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 ```bash 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 ```bash 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](/docs/trust/signing) for the full workflow.