This guide provides step-by-step instructions for installing and configuring this dotfiles repository on a fresh macOS system. Follow these instructions to set up a complete development environment with window management, shell configuration, and all supporting tools.
Estimated completion time: 90 minutes or less
- Purpose
- Prerequisites
- Quick Start (Experienced Users)
- Step-by-Step Installation
- Secrets Setup
- Verification Checklist
- Troubleshooting
- Problem: Homebrew installation fails
- Problem: Chezmoi prompts for passphrase repeatedly
- Problem: Yabai or skhd not working
- Problem: Fish shell not set as default
- Problem: Neovim shows plugin errors
- Problem: Secrets submodule not initializing
- Problem: Permission denied errors during installation
- How to roll back if needed
- Additional Help
- Post-Installation Steps
- Next Steps
- Related Documentation
- Notes
Before beginning installation, ensure you have:
- macOS (latest version recommended, tested on macOS 15.0+)
- Administrator access (for installing system-level tools)
- Stable internet connection (for downloading packages and repositories)
- Basic command-line familiarity (opening Terminal, running commands)
- GitHub account with SSH keys configured (for private repository access)
If you're familiar with chezmoi and dotfiles:
# Install chezmoi and apply dotfiles in one command
sh -c "$(curl -fsLS get.chezmoi.io)" -- init --apply git@github.com:krbylit/dotfiles.gitFor first-time users, follow the detailed step-by-step instructions below.
Homebrew is the package manager for macOS and is required to install most tools in this repository.
# Install Homebrew
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"Expected result: You should see installation progress and a success message. Follow any post-installation instructions to add Homebrew to your PATH.
Post-installation setup:
# Add Homebrew to PATH (Apple Silicon Macs)
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"
# Add Homebrew to PATH (Intel Macs)
echo 'eval "$(/usr/local/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/usr/local/bin/brew shellenv)"Verify installation:
brew --versionExpected result: Version information for Homebrew (e.g., Homebrew 4.x.x)
Chezmoi is the dotfiles manager that will apply all configurations to your system.
# Install chezmoi via Homebrew
brew install chezmoiExpected result: Chezmoi is installed and available in your PATH.
Verify installation:
chezmoi --versionExpected result: Version information for chezmoi (e.g., chezmoi version 2.x.x)
This step clones the dotfiles repository into chezmoi's source directory.
# Initialize chezmoi with the dotfiles repository
chezmoi init git@github.com:krbylit/dotfiles.gitExpected result: The repository is cloned to ~/.local/share/chezmoi
During initialization, you will be prompted for:
- Secrets repository URL (optional): Enter the
git@github.comURL to your private secrets repository, or press Enter to skip - GPG passphrase: Enter a passphrase for encrypting sensitive files (you'll need to remember this)
Note: These values are stored in ~/.config/chezmoi/chezmoi.toml on your local machine for future use.
Before applying changes to your system, review what will be modified:
# See what changes will be made
chezmoi diff
# Interactively review and approve changes
chezmoi apply --dry-run --verboseExpected result: A diff showing all files that will be created or modified. Review this output to understand what chezmoi will do.
Important files to note:
- Shell configuration:
~/.config/fish/ - Neovim configuration:
~/.config/nvim/ - Window manager:
~/.config/yabai/,~/.config/skhd/ - Git configuration:
~/.gitconfig - And many more tool configurations
Apply all dotfiles to your system:
# Apply all configurations
chezmoi applyExpected result: All configuration files are created in their target locations. Several setup scripts will run automatically:
- Secrets submodule setup (if configured)
- Homebrew package installation via
~/Brewfile(this will take 15-30 minutes) - Fish shell configuration and fisher plugin setup
- Additional tools installation (Rust, Nix, npm packages, cargo packages, etc.)
Note: The Homebrew installation step installs many packages. You'll see progress for each package being installed or updated.
After installation, change your default shell to Fish:
# Add Fish to allowed shells (if not already present)
echo /opt/homebrew/bin/fish | sudo tee -a /etc/shells
# Set Fish as default shell
chsh -s /opt/homebrew/bin/fishExpected result: Fish is now your default shell. Close and reopen your terminal to see the new Fish shell with Starship prompt.
Several tools require special macOS permissions to function properly. Grant these permissions manually:
- Open System Settings > Privacy & Security > Accessibility
- Click the lock icon to make changes
- Click the + button and add
/opt/homebrew/bin/yabai - Ensure the checkbox next to yabai is checked
Alternative: Grant permission via command line:
# Start yabai service
yabai --start-service
# Follow prompts to grant accessibility permissions- Open System Settings > Privacy & Security > Accessibility
- Click the lock icon to make changes
- Click the + button and add
/opt/homebrew/bin/skhd - Ensure the checkbox next to skhd is checked
Alternative: Grant permission via command line:
# Start skhd service
skhd --start-service
# Follow prompts to grant accessibility permissions- Open Karabiner Elements (it should auto-start after installation)
- Follow the setup wizard to grant the following permissions:
- Input Monitoring (System Settings > Privacy & Security > Input Monitoring)
- Accessibility (System Settings > Privacy & Security > Accessibility)
- Restart Karabiner Elements after granting permissions
- Open Hammerspoon (located in
/Applications) - Grant Accessibility permission when prompted
- Open System Settings > Privacy & Security > Accessibility
- Ensure Hammerspoon is checked
Start the window manager and hotkey daemon:
# Start yabai and skhd (managed by Homebrew services)
brew services start yabai
brew services start skhdExpected result: Yabai and skhd are running. You should notice window tiling behavior when opening new applications.
Verify services are running:
brew services listExpected result: yabai and skhd show status as started
Secrets management in this repository uses a combination of GPG encryption and a git submodule.
This repository manages secrets through:
- Secrets submodule: A separate private git repository containing sensitive configuration files
- GPG encryption: Chezmoi encrypts files marked with
encrypted_*prefix using your passphrase - 1Password integration (optional): Service account for accessing secrets programmatically
If you provided a secrets repository URL during Step 3, the submodule is automatically initialized. To verify:
# Check secrets submodule status
cd ~/.local/share/chezmoi
git submodule statusExpected result: The secrets submodule shows as initialized (no - prefix)
If the submodule wasn't initialized:
# Manually initialize secrets submodule
cd ~/.local/share/chezmoi
git submodule update --init --recursiveYour GPG passphrase was configured during Step 3. This passphrase is used to:
- Decrypt files prefixed with
encrypted_*in the repository - Encrypt new sensitive files you add to chezmoi
Important: Store this passphrase securely. You'll need it when:
- Setting up this repository on additional machines
- Editing encrypted files with
chezmoi edit
To edit encrypted files:
# Chezmoi automatically decrypts/re-encrypts when editing
chezmoi edit ~/.path/to/encrypted/fileIf using 1Password for secret management:
- Create a 1Password service account at 1Password.com
- Generate a service account token
- Set the token in your environment:
# Add to Fish config
echo 'set -gx OP_SERVICE_ACCOUNT_TOKEN "your-token-here"' >> ~/.config/fish/config.fish- Verify configuration:
# Check 1Password integration
chezmoi execute-template "{{ (onepassword \"item-name\").password }}"Note: This repository is configured for onepassword.mode="service" in .chezmoi.toml
To add new secret files to the repository:
# Encrypt a file when adding to chezmoi
chezmoi add --encrypt ~/.config/tool/secret-config.conf
# Or manually create with encrypted_ prefix
chezmoi add ~/.config/tool/encrypted_secret-config.confFor more detailed secrets workflows, see docs/workflows/secrets-management.md (to be created in task T010).
After installation, verify everything is working correctly:
- Fish shell loads successfully: Close and reopen terminal, confirm Fish prompt appears
- Starship prompt appears: You should see a customized prompt with git information
- Fish functions are available: Run
functionsto see custom functions list
Test commands:
# Verify Fish version
fish --version
# Test a custom Fish function
lg # Should open lazygit if available- Code formatters are installed: Verify formatters are in PATH
Test commands:
# Verify formatters
stylua --version # Lua formatter
fish_indent --version # Fish formatter
shfmt --version # Shell script formatter
prettier --version # JavaScript/TypeScript/Markdown formatter
yapf --version # Python formatter- Pre-commit hooks are active: Test pre-commit functionality
Test commands:
cd ~/.local/share/chezmoi
pre-commit run --all-filesExpected result: Pre-commit runs gitleaks and other configured hooks
- Yabai has accessibility permissions: Verify in System Settings
- Skhd has accessibility permissions: Verify in System Settings
- Window tiling works: Open multiple applications and verify tiling behavior
Test window management:
# Check yabai is running
yabai -m query --windows
# Test a hotkey (default: Cmd+Shift+Return opens terminal)
# Try using defined hotkeys from skhd configuration- Karabiner has input monitoring permissions: Verify in System Settings
- Karabiner has accessibility permissions: Verify in System Settings
- Keyboard modifications work: Test your custom key mappings
Test Karabiner:
# Check Karabiner status
karabiner_cli --show-current-profile-name- Neovim opens without errors: Launch Neovim and verify plugins load
Test Neovim:
# Open Neovim
nvim
# Inside Neovim, check health
:checkhealthExpected result: No critical errors in :checkhealth output
- Git is configured: Verify your git identity and aliases
Test git:
# Check git config
git config --get user.name
git config --get user.email
# Test git alias
git st # Should run 'git status' via alias- Homebrew packages installed: Check Brewfile packages
# List installed packages
brew list- Fisher plugins installed: Check Fish plugin manager
# List fisher plugins
fisher listSymptoms:
- Error messages during Homebrew installation
brewcommand not found after installation
Solution:
- Ensure you have administrator access and can use
sudo - Check internet connection
- Review Homebrew installation logs for specific errors
- Try installing Homebrew manually before running chezmoi
- Ensure PATH is updated with Homebrew location (see Step 1)
Symptoms:
- Passphrase prompt appears multiple times during
chezmoi apply - Passphrase is not saved between sessions
Solution:
-
Check that
~/.config/chezmoi/chezmoi.tomlexists and contains passphrase -
Verify GPG configuration in chezmoi.toml:
encryption = "gpg" [gpg] symmetric = true args = ["--batch", "--passphrase", "your-passphrase", "--no-symkey-cache"]
-
Re-initialize chezmoi if configuration is incorrect:
chezmoi init --force git@github.com:krbylit/dotfiles.git
Symptoms:
- Window tiling doesn't work
- Hotkeys don't respond
- Service shows as "error" in
brew services list
Solution:
-
Verify accessibility permissions are granted (see Step 7)
-
Check service status and logs:
brew services list brew services restart yabai brew services restart skhd # Check logs tail -f /opt/homebrew/var/log/yabai/yabai.err.log tail -f /opt/homebrew/var/log/skhd/skhd.err.log -
Disable System Integrity Protection (SIP) if needed for advanced yabai features:
- Restart Mac in Recovery Mode (hold Cmd+R during boot)
- Open Terminal from Utilities menu
- Run
csrutil disable - Restart Mac
- Warning: This reduces system security, only do if necessary
Symptoms:
- Terminal still opens with zsh or bash
- Fish prompt doesn't appear on new terminal windows
Solution:
-
Verify Fish is in
/etc/shells:cat /etc/shells | grep fish -
If not present, add it:
echo /opt/homebrew/bin/fish | sudo tee -a /etc/shells
-
Change default shell:
chsh -s /opt/homebrew/bin/fish
-
Completely quit and reopen Terminal.app (Cmd+Q, then relaunch)
Symptoms:
- Neovim displays error messages on startup
- Plugins don't load or function incorrectly
- LSP servers not working
Solution:
-
Open Neovim and run the plugin manager:
:Lazy sync -
Check Neovim health:
:checkhealth
-
Install missing dependencies noted in checkhealth output
-
For LSP issues, install language servers via Mason:
:Mason
-
Rebuild plugins if necessary:
:Lazy clean :Lazy sync
Symptoms:
secrets/directory is empty- Encrypted files can't be decrypted
- Error messages about missing secrets
Solution:
-
Verify you have access to the secrets repository
-
Manually initialize the submodule:
cd ~/.local/share/chezmoi git submodule update --init --recursive
-
If URL is incorrect, update
.gitmodules:chezmoi edit ~/.local/share/chezmoi/.gitmodules -
Re-run submodule initialization
Symptoms:
- Scripts fail with "Permission denied"
- Unable to create directories or files
Solution:
-
Ensure you have write permissions to your home directory
-
Check file permissions on chezmoi source directory:
ls -la ~/.local/share/chezmoi -
Fix permissions if needed:
chmod +x ~/.local/share/chezmoi/.chezmoiscripts/*.sh
-
Run chezmoi apply again:
chezmoi apply
If something goes wrong during installation, you can roll back changes:
# Remove applied dotfiles (WARNING: This removes all configs)
chezmoi purge
# Remove chezmoi source directory
rm -rf ~/.local/share/chezmoi
# Restore backed up configs if you made backups
# (chezmoi creates backups in ~/.local/share/chezmoi/backups by default)Note: Rolling back will remove all configurations. Make sure you have backups of any important files before purging.
For more detailed troubleshooting:
- See TROUBLESHOOTING.md for comprehensive troubleshooting guide (to be created)
- Check tool-specific READMEs in
~/.local/share/chezmoi/dot_config/<tool>/README.md - Review chezmoi documentation: chezmoi.io
- Check GitHub issues in the dotfiles repository
Some tools are not installed automatically via Homebrew and require manual installation:
Download and install from docker.com
Shows yabai status in menu bar:
# Install from GitHub releases
# https://github.com/xiamaz/YabaiIndicatorInstall these extensions for enhanced workflow:
Now that everything is installed, explore and customize:
-
Read tool-specific documentation:
# Navigate to config directories cd ~/.config/fish && cat README.md cd ~/.config/nvim && cat README.md cd ~/.config/yabai && cat README.md
-
Learn the chezmoi workflow:
- See CHEZMOI.md for detailed workflow guide (to be created)
- Practice making configuration changes safely
-
Explore custom Fish functions:
# List all custom functions functions # See function documentation # (TOOLS.md to be created in dot_config/fish/)
-
Review keymaps:
- See docs/KEYMAPS.md for unified keymap reference (to be created)
- Learn window management shortcuts
- Understand Neovim keybindings
If you plan to use these dotfiles on multiple machines:
-
Set up SSH keys on new machines for GitHub access
-
Follow this installation guide on each machine
-
Keep machines in sync:
# Pull latest changes chezmoi update # Push local changes cd ~/.local/share/chezmoi git add . git commit -m "Update configuration" git push
For detailed multi-machine workflows, see docs/workflows/multi-machine-sync.md (to be created).
Congratulations! Your development environment is now set up. Here's what to do next:
- Restart your computer to ensure all services and permissions are fully active
- Learn the keyboard shortcuts: Review
~/.config/skhd/skhdrcfor window management hotkeys - Customize your setup: Modify configurations using the chezmoi workflow
- Explore installed tools: Try out lazygit, yazi, neovim, and other TUI applications
- Read additional documentation:
- CHEZMOI.md - How to modify configurations
- README.md - Repository overview
- Tool-specific READMEs in
~/.config/<tool>/
- CHEZMOI.md - Chezmoi workflow guide for making configuration changes
- TROUBLESHOOTING.md - Comprehensive troubleshooting reference
- README.md - Repository overview and quick reference
- docs/KEYMAPS.md - Unified keyboard shortcuts reference
- docs/ARCHITECTURE.md - System architecture and design
- docs/workflows/ - Workflow guides for common tasks
- Installation time varies: Depending on internet speed and hardware, installation can take 30-90 minutes
- Homebrew installs many packages: The Brewfile contains 100+ packages for a complete development environment
- Permissions are critical: Without proper accessibility permissions, yabai and skhd won't function
- SSH vs local setup: The installation scripts detect SSH connections and skip GUI-related tools on remote machines
- Backup existing configs: If you have existing configurations, chezmoi creates backups before overwriting
- Keep dotfiles updated: Regularly run
chezmoi updateto pull the latest configurations