# Den Command Reference `den` installs the `conda den` plugin subcommand and a Den system launcher under the active generation: ```text 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: ```bash 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: ```bash 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: ```bash den generations current ``` ## `den generations list` List installed generations: ```bash den generations list ``` The active generation is marked with `*`. ## `den generations validate` Validate a generation: ```bash 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: ```bash 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: ```bash 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: ```bash den update --archive /var/cache/den/den-workspace.tar.zst ``` Use `--no-activate` to install and validate the generation without switching `/den/current-system`: ```bash 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: ```bash den activate 2 ``` The command validates the generation before replacing `/den/current-system`. ## `den rollback` Roll back to the newest older generation: ```bash den rollback ``` Roll back to a specific generation: ```bash den rollback 1 ``` Rollback uses the same validation and activation path as `den activate`. ## `den prune` Print a plan for removing inactive generations: ```bash den prune --keep 1 ``` Delete the planned inactive generations: ```bash den prune --keep 1 --yes ``` The active generation is never pruned. ## `den channels` List configured workspace channels: ```bash den channels list ``` Replace the workspace channel list: ```bash 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: ```bash 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: ```bash 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: ```bash den sandbox verify --output build/sandbox-output ``` Inspect defaults or clean generated files: ```bash den sandbox inspect den sandbox clean --yes ``` ## `den seed status` Show whether first-boot NoCloud seed state exists: ```bash den seed status ``` ## `den ssh keys` List SSH host keys: ```bash den ssh keys ``` ## `den boot status` Show stage1, systemd, and boot artifact metadata state: ```bash den boot status ``` ## `den forge` Maintain Den-owned package recipes and forge metadata: ```bash 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: ```bash 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: ```bash 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: ```bash 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: ```bash 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: ```bash 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: ```bash 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.