Chapter 8: Quick Reference

A condensed reference for daily use. Bookmark this page.

Essential Commands

# Validate configuration (always do this first)
nix flake check

# Deploy to current host (auto-detects hostname and specialisation)
nixos-rebuild-auto

# Deploy to specific hosts (run on or targeted at the named machine)
sudo nixos-rebuild switch --flake .#electra
sudo nixos-rebuild switch --flake .#lena
sudo nixos-rebuild switch --flake .#vega
sudo nixos-rebuild switch --flake .#lyra

# Test without adding to boot menu (reverts on reboot)
sudo nixos-rebuild test --flake .#electra

# Build without activating
sudo nixos-rebuild build --flake .#electra

# Show what would change (dry run)
sudo nixos-rebuild dry-activate --flake .#electra

# Switch GPU tier on electra (activation controls next boot's default)
just switch-spec battery
just switch-spec igpu
just switch-spec dgpu
# Boot entries:  battery (base)  /  igpu  /  dgpu

# Update all inputs
nix flake update

# Update one input
nix flake update codex-cli-nix

# Search for packages
nix search nixpkgs <name>

# Check a package version
nix eval nixpkgs#<package>.version

# Garbage collect
sudo nix-collect-garbage -d          # Remove ALL old generations
sudo nix-collect-garbage --delete-older-than 7d  # Keep recent

# List generations
sudo nix-env --list-generations --profile /nix/var/nix/profiles/system

# Rollback to generation N
sudo nix-env --switch-generation N --profile /nix/var/nix/profiles/system
sudo /nix/var/nix/profiles/system/bin/switch-to-configuration switch

Where to Put Things

What you want to do	File to edit
Add package for all users, all hosts	modules/common/system.nix
Add desktop app for all desktop hosts	modules/desktop/apps.nix
Add package for nimmo, all hosts	home/nimmo.nix
Add package for nimmo, desktop hosts only	home/nimmo.nix behind !isServer check
Add package for nimmo, all electra tiers	hosts/electra/default.nix (or via a profile)
Add package for electra igpu + dgpu tiers only	Inside both specialisation blocks in hosts/electra/default.nix
Add package for dgpu tier only	Inside specialisation.dgpu.configuration in hosts/electra/default.nix
Add package for one host only	hosts/<hostname>/default.nix
Configure nimmo's shell, git, or dotfiles	home/nimmo.nix
Change bootloader or networking defaults	modules/common/base.nix
Change timezone or locale	modules/common/locale.nix
Change Nix build settings or binary caches	modules/common/nix-settings.nix
Change shared electra config (all tiers)	hosts/electra/default.nix (outside specialisation blocks)
Change Framework-specific hardware config	hosts/electra/framework-16.nix
Change encrypted disk layout	hosts/electra/disko.nix
Change reusable NVIDIA config	modules/hardware/nvidia-gpu.nix
Add a new reusable feature	modules/<category>/<name>.nix
Add a new user	users/<name>.nix
Add a new host	hosts/<name>/default.nix + flake.nix
Add an external flake dependency	flake.nix inputs section

File Quick Guide

flake.nix                             -- Inputs, makeNixosSystem helper, host definitions
flake.lock                            -- Pinned versions (never edit by hand)
home/nimmo.nix                        -- Nimmo's home-manager config: packages, shell, git, dotfiles
home/plasma.nix                       -- Declarative KDE Plasma settings (via plasma-manager)
hosts/electra/default.nix             -- Electra: base (battery) + igpu + dgpu specialisations
hosts/electra/framework-16.nix        -- Framework-specific hardware configuration
hosts/electra/disko.nix               -- Declarative encrypted disk layout
hosts/lena/default.nix                -- Lena: tablet mode, two users
hosts/lena/disko.nix                  -- Btrfs partition layout (lena)
hosts/vega/default.nix                -- Vega: headless server, Attic, Paseo, Docker, storage mounts
hosts/vega/disko.nix                  -- Disk partitioning (vega)
hosts/lyra/default.nix                -- Lyra: NVIDIA GPU server, Ollama, Docker media stacks
hosts/lyra/disko.nix                  -- Disk partitioning (lyra)
modules/common/base.nix               -- Foundation for ALL hosts: bootloader, networking, sops, GC
modules/common/default-config.nix     -- nixosConfig.* portability options (user, email, paths)
modules/common/locale.nix             -- en_GB, Europe/London, UK keyboard
modules/common/nix-settings.nix       -- Flakes, caches, build parallelism, allowUnfree
modules/common/sops-host.nix          -- sops-nix host key configuration
modules/common/system.nix             -- System-wide packages: git, htop, jq, sops tools, etc.
modules/boot/silent-boot.nix          -- Plymouth, quiet kernel params
modules/desktop/apps.nix              -- Desktop apps (Kate, LibreOffice, VLC, etc.)
modules/desktop/audio.nix             -- PipeWire audio configuration
modules/desktop/environment.nix       -- Desktop foundation: system.nix + fonts + printing + removable storage
modules/desktop/flatpak-apps.nix      -- Flatpak application list
modules/desktop/fonts.nix             -- Font packages and fontconfig defaults
modules/desktop/kde-plasma.nix        -- KDE Plasma 6 desktop environment
modules/hardware/bluetooth.nix        -- Bluetooth with experimental features
modules/hardware/expansion-card-mount.nix -- 1TB expansion card automount (electra only)
modules/hardware/laptop.nix           -- Shared laptop hardware (upower, powertop, endurance mode option)
modules/hardware/printing.nix         -- CUPS printing support
modules/hardware/removable-storage.nix -- udisks2, NTFS support, polkit mount rules
modules/maintenance/garbage-collection.nix -- Daily GC, 7-day age limit
modules/maintenance/btrfs-maintenance.nix  -- Monthly btrfs scrub
modules/networking/wifi-networks.nix  -- Known Wi-Fi networks (desktop hosts)
modules/networking/wireguard-vpn.nix  -- WireGuard VPN client (desktop hosts)
modules/power/auto-power-profile.nix  -- Battery-triggered switching + manual override guard
modules/power/battery-efficiency.nix  -- Reversible EPP and energy-preference tuning (laptop battery tier)
modules/profiles/ai-agents.nix        -- Codex CLI and managed Nix/Python/Beszel/Forgejo MCP clients
modules/profiles/ai-desktop.nix       -- Imports ai-agents + opencode + desktop launchers + Ollama providers
modules/profiles/gaming.nix           -- Steam, GameMode, MangoHud, Discord
modules/profiles/gui.nix              -- GUI foundation: base, desktop, kde-plasma, apps, users
modules/profiles/jobseeking.nix       -- Job-search tools and resources
modules/profiles/laptop.nix           -- Laptop profile: gui + bluetooth + laptop hardware + wifi
modules/profiles/maker.nix            -- 3D printing, electronics, CAD tools
modules/server/base.nix               -- Server foundation: SSH, mosh, network tools
modules/services/backrest.nix         -- Automated backups via Backrest/restic to NAS
modules/services/beszel-agent.nix     -- System monitoring agent (all hosts)
modules/services/btrbk-home.nix       -- Hourly btrfs snapshots of /home (electra)
modules/services/forgejo-mcp.nix      -- Vega-hosted Forgejo issues/wiki MCP service
modules/services/nixos-auto-update.nix -- Pull-only rebuild/update service with notifications
modules/profiles/ollama.nix           -- Ollama/Open WebUI profile for AMD and NVIDIA instances
modules/services/ollama-common.nix    -- Shared Ollama service helper
modules/virtualization/docker.nix     -- Docker (basic)
modules/virtualization/docker-amd.nix -- Docker with AMD iGPU (ROCm) access
modules/virtualization/docker-nvidia.nix -- Docker with NVIDIA dGPU access
users/nimmo.nix                       -- Nimmo user account definition (groups only)
users/claire.nix                      -- Claire user account (lena only)
secrets/<service-or-host>.yaml        -- Scoped encrypted secrets (sops-nix, age-encrypted)
secrets/README.md                     -- Secrets management documentation
scripts/check-flake.sh                -- Container-based flake validation (podman)

Nix Language Cheat Sheet

# Strings
"hello"
"hello ${name}"
''multi
  line''

# Lists (space-separated, no commas)
[ "a" "b" "c" ]

# Attrsets
{ key = "value"; nested.key = "value"; }

# Functions
x: x + 1
{ config, pkgs, ... }: { /* module */ }

# Let bindings
let x = 1; in x + 2

# With (bring attrset into scope)
with pkgs; [ firefox git ]

# Inherit (copy from outer scope)
{ inherit inputs; }  # same as { inputs = inputs; }

# If
if x then y else z

# Import
import ./file.nix

# Priority
lib.mkDefault value     # Low priority
lib.mkForce value       # High priority

# Conditional config
config = lib.mkIf cfg.enable { ... };

# Optional list items
lib.optionals condition [ "a" "b" ]

Module Template

Simple module (no options)

{ config, pkgs, ... }:

{
  # Set options here
  services.something.enable = true;
  environment.systemPackages = [ pkgs.something ];
}

Module with options

{ config, lib, pkgs, ... }:

let
  inherit (lib) mkEnableOption mkOption mkIf types;
  cfg = config.services.myservice;
in {
  options.services.myservice = {
    enable = mkEnableOption "my service";
    port = mkOption {
      type = types.port;
      default = 8080;
    };
  };

  config = mkIf cfg.enable {
    # Configuration that activates when enabled
  };
}

Systemd Service Template

# Oneshot service with timer
systemd.services.my-service = {
  description = "My service description";
  serviceConfig = {
    Type = "oneshot";
    ExecStart = pkgs.writeShellScript "my-service" ''
      # Script content
      echo "hello"
    '';
  };
};

systemd.timers.my-service = {
  wantedBy = [ "timers.target" ];
  timerConfig = {
    OnCalendar = "daily";     # or "hourly", "weekly", "*-*-* 00/6:00:00"
    Persistent = true;         # Catch up after sleep/shutdown
    RandomizedDelaySec = "5min";
  };
};

Useful Resources

Resource	URL
Package search	https://search.nixos.org/packages
Option search	https://search.nixos.org/options
NixOS Wiki	https://wiki.nixos.org/
NixOS Discourse	https://discourse.nixos.org/
Nix language reference	https://nix.dev/manual/nix/latest/language/
nixos-hardware modules	https://github.com/NixOS/nixos-hardware
Flake reference	https://nix.dev/manual/nix/latest/command-ref/new-cli/nix3-flake

Service Monitoring

# Check running services
systemctl list-units --type=service --state=running

# Check timers
systemctl list-timers --all

# View service logs
journalctl -u <service-name> -f               # Follow live
journalctl -u <service-name> -b               # Current boot
journalctl -u <service-name> --since "1h ago" # Last hour

# Your custom services:
journalctl -u auto-power-profile.service      # Power management
journalctl -u backrest.service                # Backups
journalctl -u beszel-agent.service            # System monitoring agent
journalctl -u nixos-auto-update.service       # Auto updates
journalctl -u nix-gc.service                  # Garbage collection
journalctl -u btrbk-home.service              # btrfs snapshots (electra)

Just Recipes

just check                          # Validate flake syntax
just deploy                         # Deploy current config (auto-detects specialisation)
just deploy igpu                    # Deploy and activate specific specialisation
just test                           # Test without adding to boot menu
just build                          # Build without activating
just switch-spec igpu               # Switch specialisation without rebuild
just power-profile powersave        # Temporarily set profile; auto resumes at <=25%
just power-profile auto             # Return to automatic power profile switching
just plasma-capture                 # Capture current KDE Plasma settings to home/plasma.nix
just add-host HOSTNAME              # Scaffold a new host directory
just add-secret HOSTNAME            # Register a new host for secret decryption
just edit-secrets <scope>            # Edit one scoped encrypted secret file
just gc                             # Run garbage collection
just generations                    # List system generations
just firmware-update                # Update firmware via LVFS

Update Commands

just auto-update-run-now       # Trigger scheduled update immediately
just auto-update-last-run      # Show last run status
sudo nixos-auto-update --force       # Force flake update (ignore 6h freshness window)
just diff-last-update                # Show package changes between last two generations
cat /var/log/nixos-auto-update-error.log  # Inspect error if last run failed

Git Workflow Summary

# Before making changes
git pull --rebase --autostash

# After editing files
git pull --rebase --autostash # Re-run before committing if time has passed
git add <new-files>        # Stage new files (required for flakes)
nix flake check            # Validate
nixos-rebuild-auto         # Deploy
git add -A
git commit -m "description of change"
git push

# Undo uncommitted changes
git restore <file>         # Restore one file
git restore .              # Restore everything

# Undo a bad flake update
git log --oneline flake.lock
git checkout <good-commit> -- flake.lock
nixos-rebuild-auto
git commit -m "revert: Roll back flake inputs"
git push