home/docs/usage.md

Usage Guide

This guide provides detailed instructions for using and maintaining your Nix Home Manager configuration.

Table of Contents

1. Initial Setup on a New Machine
2. Switching Between Profiles
3. Adding New Packages
4. Adding New Configuration Modules
5. Updating Flake Inputs
6. Day-to-Day Operations
7. Troubleshooting

---

Initial Setup on a New Machine

Step 1: Install Nix

# Install Nix with the official installer
curl -L https://nixos.org/nix/install | sh

# Follow the prompts and restart your terminal
# Or source the nix profile manually:
. /nix/var/nix/profiles/default/etc/profile.d/nix-daemon.sh

Step 2: Enable Flakes

Flakes are an experimental feature that needs to be enabled:

mkdir -p ~/.config/nix
cat >> ~/.config/nix/nix.conf << EOF
experimental-features = nix-command flakes
EOF

Step 3: Install Homebrew (macOS only)

Homebrew is required for GUI applications:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Add Homebrew to PATH (for Apple Silicon Macs)
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"

Step 4: Install 1Password and Configure SSH Agent

1. Download and install 1Password
2. Sign in to your 1Password account
3. Enable SSH Agent:
   • Open 1Password → Settings → Developer
   • Enable "SSH Agent"
   • Enable "Use the SSH agent"
4. Enable CLI integration:
   • In the same Developer settings
   • Enable "Integrate with 1Password CLI"

Step 5: Clone the Repository

# Clone to ~/.dotfiles (recommended location)
git clone <repository-url> ~/.dotfiles
cd ~/.dotfiles

Step 6: Build and Apply Configuration

For a personal machine:

# First-time build (creates darwin-rebuild command)
nix build .#darwinConfigurations.personal.system

# Apply the configuration
./result/sw/bin/darwin-rebuild switch --flake .#personal

For a work machine:

# First-time build
nix build .#darwinConfigurations.work.system

# Apply the configuration
./result/sw/bin/darwin-rebuild switch --flake .#work

Step 7: Restart Your Shell

# Start a new shell to pick up all changes
exec zsh

Step 8: Verify Installation

# Check that key tools are available
which starship    # Should show nix store path
which atuin       # Should show nix store path
which nvim        # Should show nix store path

# Verify git configuration
git config --get user.email
git config --get user.signingkey

---

Switching Between Profiles

Switching from Personal to Work

If you need to reconfigure a machine from personal to work:

cd ~/.dotfiles
darwin-rebuild switch --flake .#work

Note: This will:

• Change git configuration (email, signing key)
• Update SSH hosts
• Remove personal-only Homebrew casks
• Disable personal-only features (like jellyfin-tui)

Switching from Work to Personal

cd ~/.dotfiles
darwin-rebuild switch --flake .#personal

Note: This will:

• Change git configuration to personal settings
• Update SSH hosts
• Install personal Homebrew casks (darktable, signal, proton-*, steam)
• Enable personal features

Temporary Profile Testing

To test a profile without fully switching:

# Build without applying
darwin-rebuild build --flake .#work

# Inspect what would change
ls -la result/

---

Adding New Packages

Adding CLI Tools via Nix (Recommended)

Edit modules/home/packages.nix:

home.packages = with pkgs; [
  # ... existing packages ...
  
  # Add your new package
  your-new-package
];

Then rebuild:

darwin-rebuild switch --flake .#personal  # or .#work

Finding Package Names

# Search for packages
nix search nixpkgs your-package-name

# Or use the online search
# https://search.nixos.org/packages

Adding GUI Applications via Homebrew

Edit modules/darwin/homebrew.nix:

For All Machines (Shared)

casks = {
  shared = [
    # ... existing casks ...
    "your-new-app"
  ];
};

For Personal Machine Only

casks = {
  personal = [
    # ... existing personal casks ...
    "personal-only-app"
  ];
};

Then rebuild:

darwin-rebuild switch --flake .#personal

Adding Homebrew Formulae (Non-Nix CLI tools)

For CLI tools that must come from Homebrew (e.g., from custom taps):

# In modules/darwin/homebrew.nix
brews = [
  # ... existing brews ...
  "tap-name/formula-name"
];

Adding Homebrew Taps

# In modules/darwin/homebrew.nix
taps = [
  # ... existing taps ...
  "owner/repo"
];

---

Adding New Configuration Modules

Creating a New Home Manager Module

1. Create a new file in modules/home/:

touch modules/home/your-module.nix

2. Add the module structure:

# modules/home/your-module.nix
{ config, pkgs, lib, ... }:

with lib;

let
  cfg = config.modules.yourModule;
in {
  options.modules.yourModule = {
    enable = mkEnableOption "Your module description";
    
    # Add your options here
    someSetting = mkOption {
      type = types.str;
      default = "default-value";
      description = "Description of this setting";
    };
  };

  config = mkIf cfg.enable {
    # Your configuration here
    programs.someProgram = {
      enable = true;
      # ...
    };
  };
}

3. Import the module in home/default.nix:

imports = [
  # ... existing imports ...
  ../modules/home/your-module.nix
];

4. Enable the module:

# In home/default.nix or profile-specific file
modules.yourModule = {
  enable = true;
  someSetting = "custom-value";
};

Creating Profile-Specific Configuration

For settings that differ between personal and work:

1. Add options to your module with sensible defaults
2. Override in profile files:

# home/personal.nix
modules.yourModule = {
  enable = true;
  someSetting = "personal-value";
};

# home/work.nix
modules.yourModule = {
  enable = true;
  someSetting = "work-value";
};

Adding Application Configuration Files

For apps without Home Manager modules, use home.file:

# In modules/home/apps.nix or a new module
home.file = {
  ".config/your-app/config.toml".text = ''
    # Your config content
    setting = "value"
  '';
  
  # Or copy from a file
  ".config/your-app/config.toml".source = ./files/your-app-config.toml;
};

---

Updating Flake Inputs

Update All Inputs

cd ~/.dotfiles

# Update all inputs to their latest versions
nix flake update

# Review changes
git diff flake.lock

# Apply the updates
darwin-rebuild switch --flake .#personal

Update Specific Input

# Update only nixpkgs
nix flake lock --update-input nixpkgs

# Update only home-manager
nix flake lock --update-input home-manager

# Update only nix-darwin
nix flake lock --update-input nix-darwin

Pin to Specific Version

Edit flake.nix to pin an input:

inputs = {
  # Pin to specific commit
  nixpkgs.url = "github:nixos/nixpkgs/abc123...";
  
  # Pin to specific branch
  nixpkgs.url = "github:nixos/nixpkgs/nixos-24.05";
};

Check for Updates

# Show current input versions
nix flake metadata

# Show what would be updated
nix flake update --dry-run

---

Day-to-Day Operations

Rebuilding After Changes

cd ~/.dotfiles

# Make your changes to .nix files
vim modules/home/packages.nix

# Rebuild and switch
darwin-rebuild switch --flake .#personal

Quick Rebuild Alias

Add to your shell configuration or use directly:

# Alias for quick rebuilds
alias rebuild="darwin-rebuild switch --flake ~/.dotfiles#personal"
alias rebuild-work="darwin-rebuild switch --flake ~/.dotfiles#work"

Checking Configuration Validity

# Validate the flake
nix flake check

# Build without switching (dry run)
darwin-rebuild build --flake .#personal

Viewing Generation History

# List all generations
darwin-rebuild --list-generations

# See what's in the current generation
ls -la /run/current-system

Rolling Back

# Rollback to previous generation
darwin-rebuild --rollback

# Switch to specific generation
darwin-rebuild switch --generation 42

Garbage Collection

# Remove old generations (keeps current)
nix-collect-garbage

# Remove all old generations
nix-collect-garbage -d

# Remove generations older than 30 days
nix-collect-garbage --delete-older-than 30d

Development Shell

For working on this repository:

cd ~/.dotfiles

# Enter development shell with formatting tools
nix develop

# Format all Nix files
nixfmt **/*.nix

---

Troubleshooting

Common Issues

"experimental-features" Error

Problem: error: experimental Nix feature 'flakes' is disabled

Solution:

mkdir -p ~/.config/nix
echo "experimental-features = nix-command flakes" >> ~/.config/nix/nix.conf

Homebrew Cask Installation Fails

Problem: A cask fails to install during rebuild

Solution:

# Update Homebrew
brew update

# Check for issues
brew doctor

# Try installing manually first
brew install --cask problematic-cask

# Then rebuild
darwin-rebuild switch --flake .#personal

SSH Key Not Found

Problem: Git operations fail with SSH key errors

Solution:

1. Ensure 1Password SSH agent is enabled
2. Check the key is in 1Password
3. Verify the public key file exists:

   ls -la ~/.ssh/keys/
   

4. Test SSH connection:

   ssh -T git@github.com
   

Build Fails with "attribute not found"

Problem: error: attribute 'somePackage' missing

Solution:

# Update flake inputs
nix flake update

# Search for correct package name
nix search nixpkgs package-name

Conflicting Files

Problem: error: collision between ... and ...

Solution:

1. Check if the file is managed by multiple sources
2. Remove manual file if it exists:

   rm ~/.config/conflicting-file
   

3. Rebuild

Debug Mode

For detailed error information:

# Build with trace
darwin-rebuild switch --flake .#personal --show-trace

# Even more verbose
darwin-rebuild switch --flake .#personal --show-trace --verbose

Interactive Debugging

# Open Nix REPL with flake loaded
nix repl
:lf .
# Now you can inspect the configuration
darwinConfigurations.personal.config.home-manager.users.alice.home.packages

Reset to Clean State

If things are badly broken:

# Remove result symlink
rm -f result

# Clean Nix store
nix-collect-garbage -d

# Remove home-manager generations
rm -rf ~/.local/state/home-manager

# Rebuild from scratch
nix build .#darwinConfigurations.personal.system
./result/sw/bin/darwin-rebuild switch --flake .#personal

Getting Help

# Home Manager options
man home-configuration.nix

# nix-darwin options
man darwin-configuration.nix

# Search for options online
# https://home-manager-options.extranix.com/
# https://daiderd.com/nix-darwin/manual/

---

Best Practices

1. Commit changes before rebuilding - Makes it easy to rollback
2. Test builds before switching - Use darwin-rebuild build first
3. Update inputs regularly - Keep packages up to date
4. Use garbage collection - Prevent disk space issues
5. Document custom modules - Add comments explaining purpose
6. Keep secrets out of Nix - Use 1Password or sops-nix for secrets