# Quick Reference

Common commands and patterns for your portable NixOS setup.

## Deployment

| Action | Command |
|--------|---------|
| **Rebuild NixOS** | `sudo nixos-rebuild switch --flake .#laptop` |
| **Rebuild Home** | `home-manager switch --flake .#myusername@linux` |
| **Both** | `sudo nixos-rebuild switch --flake .#laptop` + `home-manager switch --flake .#myusername@linux` |
| **Test (no apply)** | `sudo nixos-rebuild test --flake .#laptop` |
| **Activate Home (test)** | `home-manager build --flake .#myusername@linux` |
| **Check validity** | `nix flake check` |
| **Show outputs** | `nix flake show` |
| **Update inputs** | `nix flake update` |
| **Update one input** | `nix flake update nixpkgs` |

## Secrets

| Action | Command |
|--------|---------|
| **Generate age key** | `age-keygen -o -f ~/.config/sops/age/keys.txt` |
| **Get public key** | `age-keygen -y ~/.config/sops/age/keys.txt` |
| **Edit secrets** | `sops secrets/secrets.yaml` |
| **View secrets** | `sops -d secrets/secrets.yaml` |
| **Re-encrypt after .sops.yaml change** | `sops -e secrets/secrets.yaml > temp && mv temp secrets/secrets.yaml` |

## Development

| Action | Command |
|--------|---------|
| **Enter dev shell** | `nix develop` |
| **Format Nix files** | `nixpkgs-fmt .` |
| **Check for syntax errors** | `nix flake check` |
| **Evaluate flake** | `nix eval .#` |
| **Get derivation path** | `nix derivation show .#youruser@linux` |

## Utilities

| Action | Command |
|--------|---------|
| **List installed packages** | `nix-store -q --requisites /run/current-system` |
| **Find broken symlinks** | `nix store gc --print-roots` |
| **Clear old generations** | `sudo nix-collect-garbage -d` |
| **Clear user generations** | `nix-collect-garbage -d` |
| **Check disk usage** | `du -sh /nix` |

## Files to Edit for Common Tasks

| Task | File |
|------|------|
| **Change hostname** | `hosts/laptop/default.nix` (networking.hostName) |
| **Add system packages** | `nixos/default.nix` |
| **Add user packages** | `home/default.nix` |
| **Change shell** | `nixos/modules/shell.nix` (custom.shell.defaultShell) |
| **Enable languages** | `hosts/laptop/default.nix` (custom.development.languages) |
| **Add Git config** | `home/modules/git.nix` |
| **Customize Neovim** | `home/modules/editor.nix` |
| **Add SSH keys** | `secrets/secrets.yaml` (encrypted) |
| **Change username** | `flake.nix`, `home/default.nix`, `nixos/modules/system.nix` |

## Enable Features by Module

```bash
# Edit hosts/laptop/default.nix:

# Development tools
custom.development.enable = true;
custom.development.languages = [ "rust" "python" "nodejs" "go" "ruby" ];

# Shell setup
custom.shell.enable = true;
custom.shell.defaultShell = "zsh";  # or bash, fish

# System module
custom.system.enable = true;
```

## Debugging

| Problem | Solution |
|---------|----------|
| **Can't find package** | Check nixpkgs: `nix search nixpkgs mycpackage` |
| **Module import error** | Check imports in default.nix: `nix flake check` |
| **Config won't build** | Get detailed error: `nix flake show 2>&1 \| tail -50` |
| **Secrets not decrypting** | Verify: `sops -d secrets/secrets.yaml` |
| **Home-manager conflicts** | Backup old config: `mv ~/.bashrc ~/.bashrc.bak` |
| **Stuck rebuild** | Kill and retry: `sudo killall nixos-rebuild` |

## Git Workflow

```bash
# After making changes:
git add -A
git commit -m "Update: description"
git push

# On another machine:
git pull
sudo nixos-rebuild switch --flake .#laptop
```

## Multi-Machine Example

```bash
# Add new host
mkdir -p hosts/workstation
cp hosts/laptop/default.nix hosts/workstation/default.nix

# Add to flake.nix (copy laptop configuration block and update names)

# Deploy to new machine
sudo nixos-rebuild switch --flake .#workstation
```

## One-Liner Installers

```bash
# Fresh NixOS to existing machine
git clone <repo> ~/nix-config && cd ~/nix-config && sudo nixos-rebuild switch --flake .#laptop

# Home manager on non-NixOS
curl https://nixos.org/channels/nixos-unstable/latest-nixos-*-linux/default.nix && \
  nix run home-manager -- init --switch --flake .#myusername@linux

# Update everything
nix flake update && sudo nixos-rebuild switch --flake .#laptop && \
  home-manager switch --flake .#myusername@linux
```

## Tips

- ✅ Always commit `flake.lock` for reproducibility
- ✅ Use `lib.mkDefault` for overridable settings
- ✅ Keep secrets encrypted with sops
- ✅ Test with `test` before `switch`
- ✅ Use `--build-on-remote` for slower machines
- ✅ Check `flake check` before rebuilding
- ✅ Keep separate host configs for different machines
- ✅ Use `home-manager generations` to rollback if needed