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 |
|---|---|
|
Inspect a Den root mounted at |
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 |
|---|---|
|
Workspace archive to install. Required unless |
|
Workspace environment to install. Defaults to |
|
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.