Den Command Reference

den installs the conda den plugin subcommand and a Den system launcher under the active generation:

conda den
/run/current-system/sw/usr/lib/den/den

Assembled Den root filesystems project that launcher to /bin/den and /usr/bin/den, so a running Den system normally uses den. Both forms expose the same command surface.

Global Options

Option

Description

--root ROOT

Inspect a Den root mounted at ROOT instead of /.

DEN_ROOT can also provide the default root.

den status

Print a read-only summary of the system:

den status

The status report includes release metadata, current generation, previous generation, runtime prefix state, system prefix state, channels, boot metadata, and active generation validation state.

den doctor

Run health checks:

den doctor

Checks include:

  • /den/current-system,

  • /run/current-system,

  • active generation metadata,

  • active generation init candidates,

  • rootfs file and symlink manifests,

  • boot artifact metadata,

  • workspace manifest and lockfile,

  • writable state directories,

  • SSH host key state,

  • NoCloud seed state,

  • rootfs growth service state.

Diagnostics are printed as ok, warn, or fail. The command exits with status code 1 when any fail diagnostic is present.

den generations current

Print the active generation number:

den generations current

den generations list

List installed generations:

den generations list

The active generation is marked with *.

den generations validate

Validate a generation:

den generations validate 1

Validation checks the system prefix, conda metadata, stage1 init, an init candidate, and the current generation receipt files.

den generations diff

Compare package inventories for two generations:

den generations diff 1 2

The command reports packages that were added, removed, or changed between the two receipts.

den update --dry-run

Print the next update transaction plan:

den update --dry-run

The dry-run output reports the current generation, planned generation, workspace manifest, workspace lockfile, and target install prefix. It does not install packages or switch the active generation.

den update

Install a workspace archive as the next generation, record generation metadata, validate the result, and activate it:

den update --archive /var/cache/den/den-workspace.tar.zst

Use --no-activate to install and validate the generation without switching /den/current-system:

den update --archive /var/cache/den/den-workspace.tar.zst --no-activate

Options:

Option

Description

--archive PATH

Workspace archive to install. Required unless --dry-run is used.

--env NAME

Workspace environment to install. Defaults to system.

--no-activate

Leave the new generation inactive after validation.

The current implementation consumes an existing workspace archive. Solving, locking, and archive creation are still separate build or maintenance steps. den update calls the public conda-workspaces WorkspaceArchive API from the Den runtime environment. It does not require a separate .sha256 sidecar for the archive; provenance is tracked through the workspace archive receipt, Den generation metadata, package records, and package artifact receipts.

During the install, den update uses /var/cache/den/pkgs as the default conda package cache. It replaces an inherited /opt/den/pkgs cache setting but preserves an explicitly different CONDA_PKGS_DIRS value.

den activate

Activate an already-installed generation:

den activate 2

The command validates the generation before replacing /den/current-system.

den rollback

Roll back to the newest older generation:

den rollback

Roll back to a specific generation:

den rollback 1

Rollback uses the same validation and activation path as den activate.

den prune

Print a plan for removing inactive generations:

den prune --keep 1

Delete the planned inactive generations:

den prune --keep 1 --yes

The active generation is never pruned.

den channels

List configured workspace channels:

den channels list

Replace the workspace channel list:

den channels set https://packages.den-os.org/den-forge/den-2026.6 conda-forge

This edits /etc/den/conda.toml. It does not rewrite the lockfile or install a new generation by itself.

Print the active Den package release train from the forge metadata:

den channels release-train

This reads DEN_FORGE_REPO when set, then sibling den-forge metadata, then falls back to the built-in default release train.

den sandbox

Run a command in a Den sandbox:

den sandbox run \
  --backend qemu \
  --image registry.den-os.org/den-agent:2026.6 \
  --workspace . \
  --output build/sandbox-output \
  --network none \
  --memory 4g \
  --cpus 2 \
  --timeout 1200 \
  -- python -m pytest

The default backend is qemu. Docker, Podman, and Apple container are convenience backends that consume the same OCI image.

Verify the receipt and output digest:

den sandbox verify --output build/sandbox-output

Inspect defaults or clean generated files:

den sandbox inspect
den sandbox clean --yes

den seed status

Show whether first-boot NoCloud seed state exists:

den seed status

den ssh keys

List SSH host keys:

den ssh keys

den boot status

Show stage1, systemd, and boot artifact metadata state:

den boot status

den forge

Maintain Den-owned package recipes and forge metadata:

den forge validate
den forge recipes list
den forge recipes changed --base origin/main --head HEAD
den forge recipes render
den forge recipes build
den forge recipes verify-artifacts
den forge recipes write-receipt
den forge index

These commands are host maintainer commands for the package-forge checkout. Run them from den-forge, or set DEN_REPO to that checkout. Release publication is handled by den-os/den-forge GitHub Actions.

den workspace

Prepare the conda workspaces used for image assembly:

den workspace lock
den workspace install system
den workspace install runtime
den workspace archive

These commands wrap the repository’s conda-workspaces flow. The ct run ... workflow tasks add dependency ordering around them.

den image

Build Den image artifacts:

den image early-boot
den image assemble-rootfs
den image rootfs --rootfs build/rootfs --output build/artifacts/den-rootfs.ext4
den image qemu-bundle --target qemu-aarch64
den image qemu-bundle --target linux-64
den image uefi --target qemu-aarch64
den image oci --target qemu-aarch64 --help
den image virtualbox --target qemu-aarch64

The ct run ... tasks call these command modules directly.

den verify

Verify Den artifact receipts:

den verify rootfs --rootfs build/rootfs
den verify rootfs-image --image build/artifacts/den-rootfs.ext4
den verify qemu-bundle --target qemu-aarch64
den verify uefi --target qemu-aarch64
den verify release --release build/release --version 2026.6-rc.1 \
  --package-train den-2026.6

Receipts use an in-toto Statement v1 envelope with a Den artifact predicate. The command validates the vendored JSON schemas offline first, then recomputes artifact hashes, rootfs tree digests, and receipt input hashes where the receipt contains local input paths. These receipts are integrity and provenance documents; they are not signatures.

den release

Prepare or download a complete release directory:

den release prepare --help
den release download --help

den release prepare writes the version index, SHA256SUMS, and aggregate in-toto release receipt from per-target files and digest-pinned OCI image references. den release download trusts only a receipt whose Sigstore bundle has already been authenticated, downloads the subjects declared by that receipt, and verifies the complete local release before returning.

den smoke

Run artifact smoke checks:

den smoke rootfs
den smoke rootfs --runner chroot
den smoke generation
den smoke qemu --kind systemd
den smoke qemu-bundle
den smoke qemu-bundle --runner native
den smoke oci
den smoke uefi
den smoke uefi --runner native

These commands own staged-rootfs, generation update/rollback, QEMU, bundle, OCI, and UEFI smoke orchestration.

den report

Generate reports from Den artifacts:

den report packages --rootfs build/rootfs --output-dir build/artifacts/reports

den report packages reads the active staged generation’s conda prefix through conda prefix metadata and writes conda-packages.json and conda-licenses.md. ct run package-report remains a convenience target over this command.