alee/dotfiles
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
9d632c16edd11c559f2f7a4e0440ee7be2b49212
dotfiles/docs/SETUP_GUIDE.md
Aaron D. Lee 9d632c16ed Setup wizard improvments.
2025-12-15 21:11:15 -05:00

14 KiB
Raw Blame History

Setup Guide

Complete guide for installing, configuring, and maintaining your dotfiles.

Table of Contents

Prerequisites

Required:

  • Git
  • Curl
  • Zsh (installed automatically if missing)

Optional (for full features):

  • fzf - For command palette and fuzzy finding
  • age or gpg - For secrets vault
  • gum - For beautiful setup wizard

Installation Methods

Method 1: Interactive Wizard (Recommended)

The wizard provides a beautiful TUI to customize your installation:

git clone https://github.com/adlee-was-taken/dotfiles.git ~/.dotfiles
cd ~/.dotfiles
./install.sh --wizard

The wizard will guide you through:

  1. Identity setup (name, email, GitHub)
  2. Git configuration
  3. Feature selection
  4. Theme choice
  5. Advanced options

Method 2: One-liner

Quick install with defaults:

curl -fsSL https://raw.githubusercontent.com/adlee-was-taken/dotfiles/main/install.sh | bash

Method 3: Standard Install

Clone and run with prompts:

git clone https://github.com/adlee-was-taken/dotfiles.git ~/.dotfiles
cd ~/.dotfiles
./install.sh

Install Options

./install.sh                    # Interactive install
./install.sh --wizard           # TUI wizard
./install.sh --skip-deps        # Skip dependency installation
./install.sh --deps-only        # Only install dependencies
./install.sh --uninstall        # Remove symlinks
./install.sh --uninstall --purge # Remove everything
./install.sh --help             # Show all options

Post-Install Setup

1. Verify Installation

dotfiles-doctor.sh

This checks:

  • All symlinks are valid
  • Zsh plugins installed
  • Git configured
  • Theme loaded
  • Optional tools present

Fix issues automatically:

dotfiles-doctor.sh --fix

2. Restart Shell

exec zsh
# or just close and reopen your terminal

3. Personalize Espanso (Optional)

setup-espanso.sh

This sets up your personal info for text expansion (email, name, signatures).

4. Set Up Secrets Vault (Optional)

vault init
vault set GITHUB_TOKEN "your-token-here"
vault list

5. Configure Directory Bookmarks (Optional)

bookmark projects ~/projects
bookmark work ~/work
bookmark list

Configuration

Main Configuration File

All settings are in ~/.dotfiles/dotfiles.conf:

# ============================================================================
# Identity
# ============================================================================
USER_FULLNAME="Your Name"
USER_EMAIL="you@example.com"
USER_GITHUB="yourusername"

# ============================================================================
# Git Configuration
# ============================================================================
GIT_USER_NAME=""              # Falls back to USER_FULLNAME
GIT_USER_EMAIL=""             # Falls back to USER_EMAIL
GIT_DEFAULT_BRANCH="main"
GIT_CREDENTIAL_HELPER="store"

# ============================================================================
# Feature Toggles
# ============================================================================
# Values: "true", "false", or "ask"

INSTALL_DEPS="auto"           # Auto-skip if already installed
INSTALL_ZSH_PLUGINS="true"    # zsh-autosuggestions, syntax-highlighting
INSTALL_FZF="ask"
INSTALL_BAT="ask"
INSTALL_EZA="ask"
INSTALL_ESPANSO="ask"
SET_ZSH_DEFAULT="ask"

# ============================================================================
# Advanced Features
# ============================================================================
ENABLE_SMART_SUGGESTIONS="true"   # Typo correction
ENABLE_COMMAND_PALETTE="true"     # Ctrl+Space launcher
ENABLE_SHELL_ANALYTICS="false"    # Command stats
ENABLE_VAULT="true"               # Encrypted secrets
DOTFILES_AUTO_SYNC_CHECK="true"   # Check for updates on shell start

Applying Configuration Changes

After editing dotfiles.conf:

./install.sh --skip-deps
# or just
source ~/.zshrc

Features Guide

Command Palette

Trigger: Ctrl+Space or Ctrl+P

The command palette searches:

  • ⚡ Aliases
  • λ Functions
  • ↺ Recent commands
  • 📁 Bookmarked directories
  • ⚙ Dotfiles scripts
  • ★ Quick actions
  • ⎇ Git commands (context-aware)
  • ◉ Docker commands

Keybindings in palette:

Key Action
Enter Execute command
Ctrl+E Edit command first
Ctrl+Y Copy to clipboard
Ctrl+R Refresh entries
Esc Cancel

Bookmarks:

bookmark <name> [path]    # Save bookmark (default: current dir)
bookmark list             # List all bookmarks
bookmark delete <name>    # Remove bookmark
jump <name>               # Go to bookmark
j                         # Fuzzy select bookmark

Smart Suggestions

Automatically corrects 100+ common typos:

gti → git
dokcer → docker
sl → ls
pytohn → python

Suggests aliases for frequently typed commands:

💡 You've typed 'git status' 50 times
   You already have an alias: gs

Commands:

fuck                      # Re-run last command with typo fixed

Shell Analytics

shell-stats.sh            # Full dashboard
shell-stats.sh --top 20   # Top 20 commands
shell-stats.sh --suggest  # Alias recommendations
shell-stats.sh --heatmap  # Activity by hour
shell-stats.sh --dirs     # Most visited directories
shell-stats.sh --git      # Git command breakdown
shell-stats.sh --docker   # Docker command breakdown
shell-stats.sh --export   # Export as JSON

Secrets Vault

Encrypted storage using age or gpg:

vault set KEY "value"     # Store (or prompt for value)
vault get KEY             # Retrieve
vault list                # Show all keys
vault delete KEY          # Remove
vault shell               # Print as export statements
vault export backup.enc   # Backup encrypted vault
vault import backup.enc   # Restore vault
vault status              # Show vault info

Auto-loading: Secrets are automatically loaded into your environment on shell start.

Dotfiles Sync

dotfiles-sync.sh              # Interactive sync
dotfiles-sync.sh --status     # Show sync status
dotfiles-sync.sh --push       # Push local changes
dotfiles-sync.sh --pull       # Pull remote changes
dotfiles-sync.sh --diff       # Show local changes
dotfiles-sync.sh --watch 300  # Auto-sync every 5 minutes
dotfiles-sync.sh --log        # Show sync history

Auto-check: On shell start, you'll be notified of available updates.

Password Manager Integration

Unified interface for 1Password, LastPass, and Bitwarden:

pw list                    # List all items
pw get <item>              # Get password
pw get <item> username     # Get specific field
pw otp <item>              # Get TOTP/2FA code
pw copy <item>             # Copy password to clipboard
pw search <query>          # Search items
pw provider                # Show which CLI is being used
pw lock                    # Lock session

Interactive selection (requires fzf):

pwf                        # Fuzzy search items, copy password
pwof                       # Fuzzy search items, copy OTP

Configuration in dotfiles.conf:

INSTALL_1PASSWORD="ask"    # Install 1Password CLI (op)
INSTALL_LASTPASS="ask"     # Install LastPass CLI (lpass)
INSTALL_BITWARDEN="ask"    # Install Bitwarden CLI (bw)
PASSWORD_MANAGER="auto"    # auto, 1password, lastpass, or bitwarden

Manual CLI installation:

# 1Password
brew install --cask 1password-cli  # macOS
# See: https://1password.com/downloads/command-line/

# LastPass
brew install lastpass-cli          # macOS
sudo apt install lastpass-cli      # Ubuntu

# Bitwarden
brew install bitwarden-cli         # macOS
npm install -g @bitwarden/cli      # Any platform

Dynamic MOTD

System information displayed on shell start:

┌──────────────────────────────────────────────────────────────┐
│ ✦ user@hostname                              Mon Dec 15 14:30│
├──────────────────────────────────────────────────────────────┤
│ ▲ up:4d 7h   ◆ cpu:12%     ◇ mem:8.2/32G   ⊡ 234G free     │
├──────────────────────────────────────────────────────────────┤
│ ◉4 containers  ⎇2 dirty  ↑3 updates  ●dotfiles:✓            │
└──────────────────────────────────────────────────────────────┘

Shows:

  • Uptime, CPU usage, memory, disk space
  • Docker containers running
  • Git repos with uncommitted changes
  • Available system updates
  • Dotfiles sync status

Configuration:

ENABLE_MOTD="true"         # Enable MOTD
MOTD_STYLE="compact"       # compact (box), mini (single line), or off

Manual commands:

show_motd                  # Show compact MOTD
show_motd_mini             # Show single-line MOTD
motd                       # Alias for show_motd

Customization

Adding Aliases

Edit ~/.dotfiles/zsh/.zshrc:

# Custom aliases
alias projects='cd ~/projects'
alias k='kubectl'
alias tf='terraform'

Machine-Specific Config

Create ~/.zshrc.local (not tracked by git):

# Work machine
export CORP_PROXY="http://proxy:8080"
export WORK_EMAIL="me@company.com"

# Local paths
export PATH="$HOME/work-tools/bin:$PATH"

Custom Espanso Snippets

Edit ~/.dotfiles/espanso/match/personal.yml:

matches:
  - trigger: "..myemail"
    replace: "your.email@example.com"
  
  - trigger: "..sig"
    replace: |
      Best regards,
      Your Name

Theme Customization

Edit ~/.dotfiles/zsh/themes/adlee.zsh-theme:

# Change colors
typeset -g COLOR_GREEN='%{$FG[118]%}'
typeset -g COLOR_BLUE='%{$FG[069]%}'

# Change timer threshold (seconds)
typeset -g TIMER_THRESHOLD=10

Multi-Machine Setup

Initial Setup on New Machine

# Clone your dotfiles
git clone https://github.com/YOUR_USER/dotfiles.git ~/.dotfiles
cd ~/.dotfiles
./install.sh

Syncing Changes

On Machine A (make changes):

cd ~/.dotfiles
# Edit files...
dotfiles-sync.sh --push "Added new aliases"

On Machine B (get changes):

dotfiles-sync.sh --pull
source ~/.zshrc

Automatic Sync

Enable watch mode (runs in background):

dotfiles-sync.sh --watch 300  # Check every 5 minutes

Or add to crontab:

*/30 * * * * ~/.dotfiles/bin/dotfiles-sync.sh --auto

Troubleshooting

Run the Doctor First

dotfiles-doctor.sh --fix

Common Issues

Issue Solution
Theme not loading Check ZSH_THEME="adlee" in .zshrc, run source ~/.zshrc
Zsh plugins missing Run ./install.sh (auto-installs plugins now)
Command palette not working Install fzf: ./install.sh will prompt
Vault errors Install age: brew install age or pacman -S age
Espanso not expanding Run espanso status, then espanso restart
Sync conflicts Run dotfiles-sync.sh --conflicts to see conflicts
Symlinks broken Run ./install.sh --skip-deps to recreate

Manual Fixes

Reinstall zsh plugins:

rm -rf ~/.oh-my-zsh/custom/plugins/zsh-autosuggestions
rm -rf ~/.oh-my-zsh/custom/plugins/zsh-syntax-highlighting
./install.sh --skip-deps

Reset git config:

rm ~/.gitconfig
./install.sh --skip-deps

Fix permissions:

chmod +x ~/.dotfiles/install.sh
chmod +x ~/.dotfiles/bin/*

Getting Help

# Any script
<script> --help

# Examples
./install.sh --help
vault --help
dotfiles-sync.sh --help
shell-stats.sh --help

Uninstalling

Quick Uninstall

./install.sh --uninstall

This will:

  1. Remove all symlinks
  2. Find and offer to restore backups
  3. Keep ~/.dotfiles directory

Complete Removal

./install.sh --uninstall --purge

This also removes the ~/.dotfiles directory.

Manual Uninstall

# Remove symlinks
rm ~/.zshrc ~/.gitconfig ~/.vimrc ~/.tmux.conf
rm ~/.oh-my-zsh/themes/adlee.zsh-theme
rm -rf ~/.config/espanso
rm ~/.local/bin/dotfiles-*.sh ~/.local/bin/vault.sh ~/.local/bin/shell-stats.sh

# Restore backups (if any)
ls ~/.dotfiles_backup_*

# Remove dotfiles
rm -rf ~/.dotfiles

# Optional: Remove oh-my-zsh
rm -rf ~/.oh-my-zsh

# Change shell back to bash
chsh -s /bin/bash

File Reference

Symlinks Created

Source Target
~/.dotfiles/zsh/.zshrc ~/.zshrc
~/.dotfiles/zsh/themes/adlee.zsh-theme ~/.oh-my-zsh/themes/adlee.zsh-theme
~/.dotfiles/git/.gitconfig ~/.gitconfig
~/.dotfiles/vim/.vimrc ~/.vimrc
~/.dotfiles/tmux/.tmux.conf ~/.tmux.conf
~/.dotfiles/espanso/ ~/.config/espanso
~/.dotfiles/bin/* ~/.local/bin/*

Key Files

File Purpose
dotfiles.conf Central configuration
zsh/.zshrc Main shell config
zsh/themes/adlee.zsh-theme Prompt theme
zsh/functions/smart-suggest.zsh Typo correction
zsh/functions/command-palette.zsh Fuzzy launcher
espanso/match/base.yml Text expansion snippets
espanso/match/personal.yml Personal snippets
vault/ Encrypted secrets (gitignored)

Security Notes

  • .gitignore excludes sensitive files (.env, secrets/, *.local, vault/)
  • Vault uses strong encryption (age/gpg)
  • Never commit API keys or tokens
  • Review git/.gitconfig before pushing (contains email)
  • Personal espanso snippets may contain sensitive info
Reference in New Issue View Git Blame Copy Permalink