A comprehensive, automated dotfiles management system for macOS development environments. Features a powerful CLI tool for setup, maintenance, and AI-powered development insights.
This repository contains my personal development environment configuration, managed through a custom CLI tool called dot. It uses GNU Stow for symlink management, Homebrew for package installation, and includes configurations for Fish shell, Neovim, Herdr, Git, and other essential development tools.
After installation, the dot command will be available globally for ongoing management. Running dot without arguments shows help.
dot CLI ToolThe dot command is a comprehensive management tool for your dotfiles. It handles everything from initial setup to ongoing maintenance and provides AI-powered insights.
dot init - Initial SetupComplete environment setup with all tools and configurations.
What it does:
dot update - Update Everythingpi update to update pi and its configured packagesdot doctor - Health CheckComprehensive diagnostics including:
dot check-packages - Package StatusShows which packages are installed vs. missing from your Brewfiles.
dot retry-failed - Retry Failed InstallationsAttempts to reinstall packages that failed during initial setup.
dot benchmark-shell - Fish Shell Performance BenchmarkingMeasures Fish shell startup performance with detailed analysis:
Example Output:
dot completions - Generate Fish Shell CompletionsGenerates comprehensive Fish shell completions for the dot command, including:
dot edit - Open in EditorOpens the dotfiles directory in your default editor (defined by $EDITOR).
dot stow - Update Dotfiles SymlinksRe-creates symlinks from home/ directory to your home directory (~). Use this after editing configuration files.
dot link / dot unlink - Global dot Command InstallationMakes the dot command available from any directory by creating a symlink in /usr/local/bin or ~/.local/bin.
The system provides comprehensive package management through the dot package command and uses two Brewfiles for different contexts:
packages/bundle - Base packages for all machines:
packages/bundle.work - Work-specific formula additions:
home/ to ~~/Code/work/Clone repository:
Run installation:
Restart shell or source Fish config:
Verify installation:
Method 1: Using package commands (recommended):
Method 2: Manual editing:
Edit packages/bundle or packages/bundle.work:
Then run:
home/ directory (not your actual home directory)dot stow (or dot init for full setup)The system automatically applies work-specific Git configuration for repositories under ~/Code/work/.
Command not found: dot
Package installation failures:
Broken symlinks:
pi installation issues:
dot help for command overviewdot <command> --help for specific command helpdot doctor for environment issuespackages/failed_packages_*.txthome/ directory structuredot doctor and dot check-packagesThis repository is for personal use. Feel free to fork and adapt for your own needs.
# Clone the repository
git clone https://github.com/dmmulroy/.dotfiles.git ~/.dotfiles
cd ~/.dotfiles
# Full setup (installs everything)
./dot init
# Or customize the installation
./dot init --skip-ssh --skip-font~/.dotfiles/
├── dot # Main CLI tool
├── home/ # Configuration files (stowed to ~)
│ ├── .config/
│ │ ├── fish/ # Fish shell configuration
│ │ ├── git/ # Git configuration
│ │ ├── nvim/ # Neovim configuration
│ │ ├── herdr/ # Herdr configuration
│ │ └── ...
│ └── .ideavimrc # IntelliJ IDEA Vim config
├── packages/
│ ├── bundle # Base Brewfile
│ └── bundle.work # Work-specific packages
├── CLAUDE.md # Instructions for AI assistants
└── README.md # This file# Full installation
dot init
# Skip SSH key generation
dot init --skip-ssh
# Skip font installation
dot init --skip-font
# Skip both SSH and font setup
dot init --skip-ssh --skip-fontdot updatedot doctordot check-packagesdot retry-failed# Run 10 benchmarks (default)
dot benchmark-shell
# Run specific number of benchmarks
dot benchmark-shell -r 20
# Show verbose output with individual timings
dot benchmark-shell -v
# Combine options
dot benchmark-shell -r 15 -v=> Fish Shell Startup Benchmark Results
Configuration:
Shell: fish, version 4.0.2
Runs: 10
Test: Empty script execution
Performance Results:
Average time: 0.061 seconds
Fastest time: 0.048 seconds
Slowest time: 0.078 seconds
Time range: 0.030 seconds
Performance Assessment:
✓ Good startup performance (≤100ms)dot completionsdot edit# Create/update symlinks for configuration files
dot stow# Install dot command globally (add to PATH)
dot link
# Remove global installation
dot unlink# List packages
dot package list # List all packages
dot package list base # List base packages only
dot package list work # List work packages only
# Add packages
dot package add git # Add git formula to base bundle
dot package add docker cask # Add docker cask to base bundle
dot package add kubectl brew work # Add kubectl to work bundle
# Update packages
dot package update # Update all installed packages
dot package update git # Update specific package
dot package update all base # Update only base bundle packages
dot package update all work # Update only work bundle packages
# Remove packages
dot package remove git # Remove git from any bundle
dot package remove docker base # Remove docker from base bundle onlygit clone https://github.com/dmmulroy/.dotfiles.git ~/.dotfiles
cd ~/.dotfiles./dot init# In Fish shell
source ~/.config/fish/config.fish
# Or restart terminaldot doctor# Add package using the package command
dot package add new-tool # Adds to base bundle
dot package add new-app cask # Adds cask to base bundle
dot package add work-tool brew work # Adds to work bundledot init # or brew bundle --file=./packages/bundle# Source Fish configuration
source ~/.config/fish/config.fish
# Or add to PATH manually
export PATH="$HOME/.dotfiles:$PATH"# Check what failed
dot check-packages
# Retry failed packages
dot retry-failed# Diagnose issues
dot doctor
# Re-create symlinks
dot stow# Ensure Vite+ is installed, then install pi from the tool registry
curl -fsSL https://vite.plus | bash
vp install -g @mariozechner/pi-coding-agent# Make modifications to dotfiles
# ...
# Test changes
dot doctor
# Re-stow if needed
dot stow# Install only base packages, skip optional components
dot init --skip-ssh --skip-font
# Check what's missing
dot check-packages
# Install work packages later
brew bundle --file=./packages/bundle.work# Generate Fish shell completions
dot completions
# Completions include dynamic suggestions for:
# - Package names when using package remove/update
# - All commands, subcommands, and options# Add to packages/bundle
brew "new-tool"
cask "new-app"