Just Commands

The commands below are all run with just 🡕.

just <command> <arguments>

Each command is prefixed with an icon indicating its context:

💠 Shared: available both in the project and the framework.
🔆 Framework: specific to the upstream DNF framework (dnf/).
✳️ Project: specific to the consuming project (my network).

GIT Commands

These commands work on all repositories of the project (by default src/*/, dnf, doc, and the root). The short alias is g.

✳️ `git <cmd> [project]`

Run any git command on one or all projects.

just git "log --oneline -5"       # last commits of all projects
just git "status" dnf             # git status on dnf/ only
just git "remote -v"              # remotes of all projects

✳️ `commit <message> [project]` ⭐

add -A + commit -m on one or all projects. If the message is identical to the last commit, the recipe amends instead of creating a new commit.

just commit "fix(net): update dns config"
just commit "fix(net): update dns config" dnf    # dnf/ only

✳️ `amend [project]` ⭐

Adds current changes to the last commit (--no-edit, --allow-empty).

just amend

✳️ `status [project]` ⭐

Shows the git status of one or all projects.

just status

✳️ `diff [project]`

Shows the git diff of one or all projects.

just diff

✳️ `push [project]` ⭐

Checks for an upstream branch and ahead commits before pushing.

just push

✳️ `pull [project]`

Pulls the latest changes from one or all projects.

just pull

✳️ `git-last-log`

Shows the last commit message of all projects, formatted and aligned.

just git-last-log

✳️ `git-show-repos`

Shows the list of repositories that git commands iterate over.

just git-show-repos

✳️ `update-flake`

Updates flake inputs of dnf/ then the root. If the last commit of dnf/ is already an update(flake):, it amends it.

just update-flake

✳️ `update-dnf`

Syncs flake.lock with the local HEAD of dnf/ (co-development).

just update-dnf

Development commands

These commands help maintain the code, generate declarative files and work on the Rust generator.

💠 `develop` / `d`

Runs nix develop -c zsh to get a shell with the project tools.

just develop

💠 `clean` / `c` ⭐

Runs the full chain: fix → check → generate → format → _fix_fs_permissions.

just clean

💠 `format`

Runs treefmt on all files with the framework’s shared config.

just format

💠 `fix`

Automatically fixes issues detected by statix.

just fix

💠 `generate`

Regenerates the default.nix files in module folders and the var/generated/*.nix files from etc/config.yaml.

just generate

✳️ `gen-build`

Builds the generator binary (src/generator/).

just gen-build

✳️ `gen-test`

Runs the generator unit tests.

just gen-test

✳️ `cat <host>` ⭐

Chains clean → amend → apply-local (or apply-verbose <host>).

just cat                   # applies locally
just cat myserver          # applies on myserver

Verification commands

Run these checks before deploying to catch regressions.

💠 `check`

Runs deadnix recursively on all *.nix files.

just check

💠 `check-flake`

Runs nix flake check filtering out known warnings from DNF non-standard outputs (colmena, colmenaHive, homeManagerModules, libTests).

just check-flake

💠 `check-statix`

Static analysis of Nix code with statix.

just check-statix

✳️ `check-all`

Runs DNF unit tests, DNF flake check and network flake check.

just check-all

🔆 `unit-tests` ⭐

Runs nix-unit on .#libTests.

just unit-tests

🔆 `simulate [scenario]`

Runs NixOS test scenarios (NixOS Test Driver).

Argument	Effect
(empty)	Lists available scenarios
`all`	Runs all scenarios (`nix flake check`)
`full`	Regenerates fixtures then runs everything
`<name>`	Runs a named scenario

just simulate                      # list
just simulate all                  # run all
just simulate modules-node-console-git

🔆 `simulate-debug <scenario>`

Runs the interactive driver of a scenario (Python REPL).

just simulate-debug modules-node-console-git

🔆 `fixtures <action>`

Manages test fixtures: generation, drift check, regeneration of keys and disposable secrets.

Action	Effect
`generate`	Regenerates `var/generated/` for all test spaces
`check`	Checks for drift without modifying the tree
`gen-secrets`	Regenerates test keys and secrets (disposable)

just fixtures check

Installation commands

Installing a new host follows a precise sequence.

✳️ `install <host> [user] [ip]`

Formats the disks via disko and installs NixOS via nixos-anywhere.

The ip argument defaults to auto: the address is computed the same way as for full-install, no need to read it off.

just install myserver
just install myserver nixos 10.0.0.5     # custom IP
just install myserver do=test             # test VM only

✳️ `full-install <host> [user] [ip]` ⭐

Full chain: install + wait for reboot + configure + apply + gc + reboot.

The address is computed automatically: the host name in its own zone, or the reserved roaming address if it is connected elsewhere. See Machines outside their zone.

just full-install myserver
just full-install myserver nixos 10.0.3.42   # forced address

✳️ `install-key <host>`

Formats a USB device with disko and installs NixOS on it.

just install-key myusbhost

✳️ `configure <host> [ip]`

Chains copy-id → copy-hw → push-key → luks (the last one does nothing on an unencrypted host).

The address is resolved once and passed to the whole chain. If the host is connected outside its zone, the SSH redirect is set up on the fly so that the following apply can reach it: run just roaming-clear <host> once the machine is back home.

just configure myserver

✳️ `copy-id <host>`

Copies the nix user’s public key to the target host.

just copy-id myserver

✳️ `copy-hw <host>`

Runs nixos-generate-config --show-hardware-config remotely and saves the result into usr/machines/<host>/hardware-configuration.nix.

just copy-hw myserver

✳️ `push-key <host>`

Transfers the age key /etc/sops/age/infra.key to the target host.

just push-key myserver

✳️ `luks <host> [action] [ip]`

Provisions a host’s encryption: shared and per-host passphrases in sops, usr/secrets/luks.json manifest, initrd SSH key on the target, WAN IP of the gateways. action=passwd rotates the per-host passphrase. See Disk encryption (LUKS).

just luks myserver
just luks myserver passwd

✳️ `roaming [host] [ip]`

Redirects SSH to a host connected outside its zone, for the duration of the installation. Colmena addresses a node by its name, which refers to its original address; this redirect points it to where the machine actually is.

Set up by just configure when needed, removed by full-install at the end of the run. Without arguments, displays the current redirects.

just roaming             # display
just roaming myserver    # redirect (computed address)

✳️ `roaming-clear [host]`

Removes a host’s redirect, or all of them if none is given.

just roaming-clear myserver
just roaming-clear

✳️ `configure-admin-host` ⭐

Configures the administration machine: SSH keys, SOPS age keys, .sops.yaml, default secrets, Harmonia signing key.

just configure-admin-host

💠 `build-iso [arch]`

Builds the framework ISO image for the given architecture.

just build-iso                        # x86_64-linux (default)
just build-iso "aarch64-linux"

Deployment commands

The deployment tool is colmena 🡕. All apply commands first refresh the DNF lock via update-dnf.

✳️ `apply <target> [action]` / `a` ⭐

Deploys the configuration to one or more targets.

Parameter	Description
`target`	Hostname, pattern (`'*'`), list (`a,b`), colmena tag (`@server`)
`action`	`switch` (default), `boot`, `test`, `build`

just apply @all                 # all hosts
just apply myserver             # switch (default)
just apply myserver boot        # boot
just apply 'db-*'               # all hosts starting with db-

✳️ `apply-verbose <c> [a]` / `av` ⭐

Same as apply with --verbose --show-trace.

just apply-verbose myserver

✳️ `apply-local [action]` / `al` ⭐

Applies the configuration on the current machine.

just apply-local

✳️ `apply-silenced <target> [action]`

Enables Alertmanager maintenance mode before applying, disables it after.

just apply-silenced myserver

Administration commands

These commands interact with fleet hosts: maintenance, reboot, cleanup, and boot repair.

✳️ `enter <host>` / `e` ⭐

Opens an interactive SSH session as nix@<host>. If the host is waiting for its LUKS passphrase at boot (port 22 closed), it switches to its initrd sshd (port 2222, falling back to the manifest’s WAN IP for a gateway) and presents the passphrase prompt. See Disk encryption (LUKS).

just enter myserver

✳️ `reboot <host>`

Reboots the host via colmena exec.

just reboot myserver
just reboot 'web-*'         # all web-*

✳️ `halt <host>`

Halts (poweroff) the host via colmena exec.

just halt myserver

✳️ `gc <host>` ⭐

Runs nix-collect-garbage -d then switch-to-configuration boot on the host.

just gc myserver

✳️ `fix-boot <host>`

Reinstalls the bootloader with NIXOS_INSTALL_BOOTLOADER=1.

just fix-boot myserver

✳️ `fix-zsh <host>`

Removes .zshrc.bkp on the target host.

just fix-zsh myserver

Secret management commands

Passwords and keys are encrypted with SOPS. These commands manage them without manipulating encrypted files by hand.

✳️ `sops` ⭐

Opens usr/secrets/secrets.yaml in vim (as user nix).

just sops

✳️ `passwd-default`

Sets the default password for DNF workstations (SOPS-encrypted, bcrypt-hashed).

just passwd-default

✳️ `passwd <user>` ⭐

Updates the password for a specific user.

just passwd darkone

✳️ `passwd-restic`

Generates a REST password per host and a repository password per zone.

just passwd-restic

✳️ `passwd-mas`

Generates the three secrets of the Matrix Authentication Service : internal encryption key, secret shared with Synapse, and RSA signing key.

just passwd-mas

✳️ `passwd-livekit`

Generates the shared secret of the MatrixRTC stack : the LiveKit SFU validates with it the tokens that its authorization service signs.

just passwd-livekit

✳️ `yubikey <user> [key] [action]`

Enrolls a YubiKey (main by default, or backup) for a user: PAM (session/sudo), LUKS and Kanidm enrollment link, in a single pass on the admin machine. action=revoke revokes the key across all machines at next deployment. See Strong authentication.

just yubikey darkone            # enrolls the primary key
just yubikey darkone backup     # enrolls the backup key
just yubikey darkone main revoke

✳️ `rotate init|push-keys|finalize`

Rotation of the age key /etc/sops/age/infra.key in 3 steps with integrity checks.

Step	Action
`init`	Generates a new key, keeps the old one, re-encrypts secrets
`push-keys`	Pushes the combined key (new + old) to all hosts
`finalize`	Verifies all hosts have the new key, removes the old one

just rotate init
just rotate push-keys
just rotate finalize

Advanced commands

These commands cover specific features: provisioning the Matrix alert bot and managing Kanidm replication.

✳️ `configure-alert-bot`

Creates or refreshes the Matrix bot, the webhook secret and the alert and incident rooms from the network.matrix section of config.yaml.

just configure-alert-bot

✳️ `idm-sync-certs`

Collects Kanidm replication certificates from all fleet nodes into usr/secrets/replication/.

just idm-sync-certs

✳️ `idm-fix-replica <suppl> <cons>`

Analyzes the health of Kanidm replication without modifying anything. Takes the supplier node (HCS) and the list of consumers (gateways, comma-separated).

just idm-fix-replica hcs agate,gw

Alias summary

Alias	Command
`a`	`apply`
`al`	`apply-local`
`av`	`apply-verbose`
`c`	`clean`
`d`	`develop`
`e`	`enter`
`g`	`git`
`amend`	`git-amend`
`commit`	`git-commit`
`diff`	`git-diff`
`pull`	`git-pull`
`push`	`git-push`
`status`	`git-status`

Just Commands

GIT Commands

✳️ git <cmd> [project]

✳️ commit <message> [project] ⭐

✳️ amend [project] ⭐

✳️ status [project] ⭐

✳️ diff [project]

✳️ push [project] ⭐

✳️ pull [project]

✳️ git-last-log

✳️ git-show-repos

✳️ update-flake

✳️ update-dnf

Development commands

💠 develop / d

💠 clean / c ⭐

💠 format

💠 fix

💠 generate

✳️ gen-build

✳️ gen-test

✳️ cat <host> ⭐

Verification commands

💠 check

💠 check-flake

💠 check-statix

✳️ check-all

🔆 unit-tests ⭐

🔆 simulate [scenario]

🔆 simulate-debug <scenario>

🔆 fixtures <action>

Installation commands

✳️ install <host> [user] [ip]

✳️ full-install <host> [user] [ip] ⭐

✳️ install-key <host>

✳️ configure <host> [ip]

✳️ copy-id <host>

✳️ copy-hw <host>

✳️ push-key <host>

✳️ luks <host> [action] [ip]

✳️ roaming [host] [ip]

✳️ roaming-clear [host]

✳️ configure-admin-host ⭐

💠 build-iso [arch]