#show link: underline

#set document(
  title: [NixOS Cheatsheet],
  author: "SIPB",
  description: [https://forgejo.mit.edu/SIPB/nixos-cheatsheet],
)
#set page(
  "us-letter",
  columns: 2,
  flipped: true,
  margin: 1cm,
)

#grid(
  columns: (80pt, auto),
  [#block(image("nix-snowflake-colours.svg", width: 64pt))],
  [#title()

    Revision #datetime.today().display(), made by #context document.author.first() #box(image("sipb.svg", height: 15pt))

    #context document.description],
)

#table(
  stroke: (x: none, y: 0.5pt),
  columns: (35%, auto),
  table.header(
    table.cell(fill: silver, align: center, [Task]),
    table.cell(fill: silver, align: center, [Command]),
  ),
  table.header(
    level: 2,
    repeat: false,
    table.cell(fill: aqua)[*Running software*], table.cell(fill: aqua)[],
  ),
  [Search for software],
  [```bash nix search nixpkgs hello``` #footnote[This evaluates nixpkgs so the first run may be slow, but further runs used cached results]],

  [Run program],
  [```bash nix run nixpkgs#hello``` #footnote[Pass `--` before any arguments to the program]],

  [Run program from other nixpkgs branch],
  ```bash nix run nixpkgs/nixos-25.11#hello```,

  [Run program from another flake],
  ```bash nix run nix run github:user/nixpkgs/branch#hello```,

  [Find nixpkgs revision for a specific version of a program],
  [See https://lazamar.co.uk/nix-versions/],

  [Get shell with program], ```bash nix shell nixpkgs#hello```,
  [Run AppImage], ```bash appimage-run hello.AppImage```,
  table.header(
    level: 2,
    repeat: false,
    table.cell(fill: lime)[*Building the system*], table.cell(fill: lime)[],
  ),
  [Update flake inputs], ```bash nix flake update```,
  [Build and deploy to this machine], ```bash nixos-rebuild switch --sudo```,
  [Build on remote machine and deploy to current machine],
  [```bash sudo nixos-rebuild switch --build-host user@remote --use-substitutes``` #footnote[This needs root on the current machine to add untrusted paths to the Nix store]],

  [Build on current machine and deploy to remote machine],
  [```bash nixos-rebuild switch --flake .#remote-machine-hostname --target-host root@remote``` #footnote[This needs root on the remote machine for the same reason]],

  [Build and run VM from config],
  [```bash nixos-rebuild build-vm && result/bin/run-$hostname-vm -m 4G -smp 4 -device virtio-vga-gl -display sdl,gl=on``` #footnote[You may need to change all occurrences of the QEMU version in the run script if the config uses a different nixpkgs revision than the host]],

  [Build ISO from config],
  [Add `"/installer/cd-dvd/installation-cd-minimal-new-kernel-no-zfs.nix"` as a module, then run ```bash nix build .#nixosConfigurations.$hostname.config.system.build.isoImage```],

  table.header(
    level: 2,
    repeat: false,
    table.cell(fill: yellow)[*System generations*], table.cell(fill: yellow)[],
  ),
  [List system generations], ```bash nixos-rebuild list-generations```,
  [Get changes between system generations],
  ```bash nix profile diff-closures --profile /nix/var/nix/profiles/system```,

  [Roll back one generation], ```bash nixos-rebuild switch --sudo --rollback```,
  [Switch to generation],
  ```bash sudo nix-env --switch-generation 12345 -p /nix/var/nix/profiles/system && sudo /nix/var/nix/profiles/system/bin/switch-to-configuration switch```,

  table.header(
    level: 2,
    repeat: false,
    table.cell(fill: orange)[*Store operations*], table.cell(fill: orange)[],
  ),
  [Get size of system],
  ```bash nix path-info -Sh /nix/var/nix/profiles/system```,

  [Get size of Nix store],
  ```bash sqlite3 /nix/var/nix/db/db.sqlite 'SELECT SUM(narSize) FROM ValidPaths'```,

  [Get largest packages],
  ```bash sqlite3 /nix/var/nix/db/db.sqlite 'SELECT * FROM ValidPaths ORDER BY narSize DESC LIMIT 20'```,

  [Clean Nix store], ```bash sudo nix-collect-garbage && nix store optimise```,
  [Delete generations older than 7 days],
  ```bash sudo nix-collect-garbage --delete-older-than 7d```,

  [Check what depends on path],
  ```bash nix-store --query --referrers /nix/store/aaaaaa```,

  table.header(
    level: 2,
    repeat: false,
    table.cell(fill: fuchsia)[*Nix development*], table.cell(fill: fuchsia)[],
  ),
  [Run Nix file], ```bash nix eval -f main.nix```,
  [Inspect system config in REPL],
  ```bash nix repl .#nixosConfigurations.$hostname```,

  [Format flake],
  [Add `formatter.${system} = pkgs.nixfmt-tree;` to your flake outputs, then run ```bash nix fmt```],
)