heyitsiveen

Interactive CLI to set up dotfiles for macOS and Windows 11. One command to install, theme, backup, and manage your development environment.

Table of Contents

• Quick Start
• Prerequisites
• Tools
• What's Included
• Color Themes
• CLI Flags
• How It Works
• Development

Quick Start

npx @heyitsiveen/dotfiles@latest

Or with other package runners:

bunx @heyitsiveen/dotfiles@latest
pnpm dlx @heyitsiveen/dotfiles@latest
yarn dlx @heyitsiveen/dotfiles@latest

This CLI modifies your home directory. It writes to ~/.config/, ~/.zshrc (macOS) or PowerShell profile (Windows), and other tool-specific paths. Existing configs are backed up to ~/.config/heyitsiveen/dotfiles/backup/ before any overwrite. Preview with --dry-run first. Undo with --restore or --uninstall.

Prerequisites

| Prerequisite | Why | Install | |---|---|---| | Node.js >= 22 | Running the CLI | brew install node or nodejs.org | | Nerd Font | Icons in Tide, oh-my-posh, Neovim | nerdfonts.com (recommended: JetBrains Mono NF) | | Homebrew (macOS) / winget (Windows) | Installing tools | brew.sh / pre-installed on Windows 11 |

Tools

The CLI automatically detects all tools and offers to install missing ones via Homebrew (macOS) or winget (Windows).

Required (core tools for the dotfiles):

| Tool | macOS | Windows | |---|---|---| | Git | brew install git | winget install Git.Git | | Fish Shell / PowerShell | brew install fish | winget install Microsoft.PowerShell | | Ghostty / WezTerm | brew install --cask ghostty | winget install wez.wezterm | | Neovim | brew install neovim | winget install Neovim.Neovim | | tree-sitter-cli | brew install tree-sitter-cli | npm i -g tree-sitter-cli | | C compiler | xcode-select --install | VS Build Tools |

Note: tree-sitter-cli and a C compiler are only needed if you install Neovim. LazyVim uses them to compile syntax parsers. macOS usually has the C compiler pre-installed via Xcode Command Line Tools.

Optional (enhance the experience):

| Tool | macOS | Windows | |---|---|---| | tmux | brew install tmux | N/A | | bat | brew install bat | winget install sharkdp.bat | | btop | brew install btop | winget install aristocratos.btop4win | | ripgrep | brew install ripgrep | winget install BurntSushi.ripgrep.MSVC | | fd | brew install fd | winget install sharkdp.fd | | eza | brew install eza | winget install eza-community.eza | | fastfetch | brew install fastfetch | winget install Fastfetch-cli.Fastfetch | | oh-my-posh | N/A | winget install JanDeDobbeleer.OhMyPosh |

What's Included

macOS

| Tool | Description | |---|---| | Fish Shell | config.fish, 8 conf.d modules, 7 functions, 3 Tide palette themes | | Ghostty | Terminal emulator with JetBrains Mono, 0.9 opacity, 3 themes | | WezTerm | Cross-platform terminal with Solarized/Vercel/Vesper color schemes | | tmux | 7 config files (main, keybinds, statusbar, pane, notifications, popup) | | Neovim | LazyVim with solarized-osaka, Snacks, Mason (oxfmt + oxlint), conform | | bat | Config + Vercel/Vesper custom .tmTheme themes | | btop | System monitor + 3 theme files | | ripgrep | Smart-case, hidden files, common excludes | | Claude Code | 6 MCP servers, CLAUDE.md, settings |

Windows

| Tool | Description | |---|---| | PowerShell | Profile, 5 modules, 3 functions | | oh-my-posh | 3 TOML prompt themes (Solarized, Vercel, Vesper) | | WezTerm | Windows-adapted config with tab bar | | Neovim | LazyVim (same config as macOS) | | bat | Config + custom themes | | btop | System monitor + 3 theme files | | ripgrep | Search config | | Claude Code | 6 MCP servers, CLAUDE.md, settings |

⚠️ Claude Code configs are the author's personal setup. settings.json enables specific plugins, sets effortLevel: xhigh, advisorModel: opus, and skips dangerous-mode permission prompts. .claude.json wires three MCP servers (exa, grep, better-auth). CLAUDE.md is the author's 13-rule instruction set. If you prefer defaults, deselect "Claude Code" when the CLI asks which configs to install — or replace the files in ~/.claude/ after install.

Color Themes

Three themes are available across all tools:

| Theme | Style | |---|---| | Solarized Dark | Warm, low-contrast dark theme (default) | | Vercel | Minimal, high-contrast dark theme | | Vesper | Soft, warm dark theme with orange accents |

Switch themes instantly across all installed tools:

npx @heyitsiveen/dotfiles --theme vercel
npx @heyitsiveen/dotfiles --theme vesper
npx @heyitsiveen/dotfiles --theme solarized-dark

CLI Flags

| Flag | Description | |---|---| | --platform <macos\|windows> | Skip OS detection | | --dry-run | Show planned operations without writing files | | --theme <name> | Switch theme: solarized-dark, vercel, vesper | | --restore | Restore from backup | | --uninstall | Remove installed dotfiles | | --version | Show version | | --help | Show usage |

How It Works

1. Detects your OS (macOS or Windows)
2. Checks for missing tools and offers to install them (brew/winget)
3. Shows available dotfile configurations
4. You select which configs to install
5. You pick a color theme
6. Backs up existing dotfiles (optional — Neovim backups include LazyVim plugin data)
7. Copies configs to the right locations
8. Activates your chosen theme across all tools
9. Checks for updates and notifies you if a new version is available

Subsequent runs detect the existing installation and offer:

• Fresh install — backup + overwrite
• Update — apply changes from a new package version
• Change theme — switch colors across all tools
• Uninstall — remove configs, uninstall tools (brew/winget), or both
• Restore — restore from per-tool timestamped backups

Development

# Install dependencies
npm install

# Build
npm run build

# Run locally
node dist/index.mjs

# Run all checks (typecheck + lint + format)
npm run check

# Or with bun
bun install && bun run build && bun run check

Pre-commit hooks are set up via husky + lint-staged. Every git commit automatically:

1. Formats staged .ts files with oxfmt
2. Lints staged .ts files with oxlint
3. Typechecks the project with tsc

License

MIT