Suit up!

简体中文 | English

Named after Barney's catchphrase from How I Met Your Mother.

Features

• Interactive TUI powered by @clack/prompts
• Suitup is zsh-only; run all suitup commands from a zsh session
• Modular step selection — install only what you need
• Append mode — add recommended configs to an existing .zshrc without replacing it
• Diff preview updates — reruns show safe suitup config additions before applying them
• Migrate PATH mode — move PATH/tool bootstrap lines out of .zshrc into ~/.config/zsh/core/paths.zsh
• Verify mode — check your installation integrity
• Clean mode — remove suitup config files
• --help output for quick command discovery
• Backs up existing zsh startup files to ~/.config/zsh/backups/ before changing shell startup config
• Powerlevel10k is optional; recommended because its async git status stays responsive in large repositories
• Idempotent — safe to run multiple times
• No private/company-specific content — clean, generic configs

Usage First

Recommended preflight

Suitup can bootstrap Zsh and Homebrew for you, but the most reliable path is to start after both are already working.

• Recommended: install Zsh first, switch into a Zsh session, then run suitup
• Recommended: install Homebrew first so later package/tool steps run in a known-good environment
• Optional: if you skip either one, keep the Bootstrap step selected and let suitup set them up for you
• If your setup stopped halfway, run node src/cli.js append to add missing blocks, re-install missing tools tied to those blocks, or switch the prompt preset without replacing your whole .zshrc
• When suitup detects existing suitup-managed config or already-installed frontend prerequisites, setup now deselects those completed steps by default so reruns stay focused

Install and run

When you run suitup locally from the repo, use a zsh session. The curl installer can bootstrap missing prerequisites for you on a fresh machine.

Quick install via curl

curl -fsSL https://raw.githubusercontent.com/ChangeHow/suitup/main/install.sh | bash

The installer bootstraps missing zsh and Node.js/npm when possible, downloads a temporary copy of the repo, runs npm ci, then asks whether you want interactive setup or non-interactive init before launching inside zsh. On Linux, Node.js bootstrap now uses the official Node.js 20.x binary tarball so it is not tied to a specific distro repository.

You can also pass a command directly to skip the prompt:

curl -fsSL https://raw.githubusercontent.com/ChangeHow/suitup/main/install.sh | bash -s -- init

init is a non-interactive quick-start path that uses recommended defaults:

• bootstrap package manager + zsh when needed
• install the layered zsh config
• install zinit + Powerlevel10k preset
• install recommended CLI tools and frontend tooling
• install recommended GUI apps on macOS
• write shared aliases
• run p10k configure at the end to set up your prompt theme

You can also pass any other command:

curl -fsSL https://raw.githubusercontent.com/ChangeHow/suitup/main/install.sh | bash -s -- clean

If you want append mode directly:

curl -fsSL https://raw.githubusercontent.com/ChangeHow/suitup/main/install.sh | bash -s -- append

Clone locally

git clone https://github.com/ChangeHow/suitup.git
cd suitup
npm install
node src/cli.js

Commands

Command	Description
node src/cli.js init	Non-interactive quick init with recommended defaults
node src/cli.js	Full interactive setup (default)
node src/cli.js setup	Same as above
node src/cli.js append	Append configs to existing .zshrc
node src/cli.js migrate-paths	Migrate PATH-related lines from .zshrc to ~/.config/zsh/core/paths.zsh
node src/cli.js verify	Verify installation integrity
node src/cli.js clean	Remove suitup config files
node src/cli.js --help	Show available commands

What each mode does

Setup (default)

Interactive step-by-step setup with selectable steps:

1. Zsh Config — creates ~/.config/zsh/ with layered config architecture
2. Bootstrap — package manager + Zsh
3. Plugin Manager — zinit (recommended) or skip for native zsh only
4. Prompt Preset — Powerlevel10k (recommended) or a basic zsh prompt
5. CLI Tools — bat, eza, fzf, fd, zoxide, atuin, ripgrep...
6. GUI Apps — iTerm2, Raycast, VS Code, fonts...
7. Frontend Tools — choose fnm, Node.js via fnm, pnpm, git-cz
8. Shell Aliases — git, eza, fzf shortcuts
9. SSH Key — generate GitHub SSH key
10. Vim Config — basic vim setup
11. Dock Cleanup — clean macOS Dock

Before suitup updates shell startup config, it backs up existing zsh startup files such as .zshrc, .zprofile, .zshenv, and .zlogin to ~/.config/zsh/backups/.

When rerunning setup against suitup-managed zsh files, suitup line-merges new shipped additions, renders a unified diff preview, and asks for confirmation before writing. Existing user-added lines are preserved. Files that are not marked as suitup-managed are skipped with a reason because suitup cannot safely distinguish shipped config from user-owned config.

Prompt/theme files are excluded from line-merging because they often contain generated or user-tuned state that cannot be reliably reconciled.

If you choose Powerlevel10k, suitup keeps prompt loading non-interactive during setup. When ~/.p10k.zsh is missing, it falls back to a basic prompt until you run p10k configure yourself.

On Linux, suitup disables zsh spelling correction by default to avoid disruptive IME-related corrections while typing commands.

Bootstrap details:

• macOS: install Homebrew or skip package manager setup
• Linux: choose apt-get, dnf, yum, brew, or skip for package-manager-driven steps such as installing zsh
• Linux: if you choose Homebrew and it is not installed yet, suitup installs Homebrew first and then asks you to rerun setup before the remaining brew-based steps
• Linux: when Node.js 20+ is missing, the curl installer can bootstrap it from the official Node.js 20.x Linux archive into ~/.local/share/suitup/node/ and use it only for the installer session
• The Linux bootstrap Node runtime is now kept isolated for the installer itself so it does not shadow a later fnm-managed Node.js install
• If Homebrew is already installed in a non-default location, suitup now tries common shellenv paths automatically during Zsh startup
• Suitup now also writes a minimal ~/.zshenv so non-interactive shells can still load shared env vars and PATH setup
• When fnm installs Node.js, suitup keeps both the fnm binary and the installed default Node version on PATH so fnm, node, npm, and globally installed CLIs resolve correctly in both interactive and non-interactive shells
• Frontend tool installs use a user-local npm prefix under ~/.local/ so pnpm and git-cz do not require sudo or writes to system npm directories

Append

For users who already have a .zshrc and want to cherry-pick suitup configs:

node src/cli.js append

Uses idempotent marker blocks (# >>> suitup/... >>>) to safely append selected configs and re-run related installers when required tools are missing:

• Suitup aliases
• Zinit plugins
• Powerlevel10k prompt or basic prompt preset (replaces ~/.config/zsh/shared/prompt.zsh)
• Tool initialization (atuin, fzf, zoxide, fnm)
• Zsh options (history, completion)
• Environment variables
• Startup performance monitor
• FZF configuration

For suitup-managed shared config files such as aliases and zinit plugins, append mode also previews safe line additions before applying them. Prompt/theme files are not line-merged because they often contain generated or user-tuned state that cannot be reliably reconciled.

Verify

node src/cli.js verify

Checks config files (including ~/.zshenv), CLI tool availability, and zsh syntax validity.

Migrate PATH entries

For users whose existing .zshrc has accumulated PATH=..., brew shellenv, cargo/env, fnm env, NVM_DIR, PNPM_HOME, and similar tool bootstrap lines:

node src/cli.js migrate-paths

This command:

• extracts detected PATH-related lines from .zshrc
• appends them to ~/.config/zsh/core/paths.zsh
• creates a backup in ~/.config/zsh/backups/
• runs a post-migration Zsh syntax check
• rolls back automatically if validation fails

Clean

node src/cli.js clean

Attempts a safe uninstall of suitup-managed config:

• restores the latest non-suitup backup of ~/.zshrc / ~/.zshenv when available
• removes suitup-generated ~/.config/zsh/ files when they still match shipped templates
• strips # >>> suitup/... >>> blocks from an existing ~/.zshrc if you used append
• preserves user-modified files instead of deleting them blindly

Help

node src/cli.js --help

Prints the command list and available options.

What suitup installs

CLI tools

Tool	Replaces	Description
bat	cat	Syntax-highlighted file viewer
eza	ls	Modern file listing
fzf	—	Fuzzy finder
fd	find	Fast file search
atuin	ctrl-r	Shell history search
zoxide	cd	Smart directory jumping
ripgrep	grep	Fast content search

Zsh plugins

• zsh-autosuggestions
• zsh-syntax-highlighting
• powerlevel10k theme (optional, pairs well with zinit)

GUI apps

Selectable during setup: iTerm2, Raycast, VS Code, Itsycal, Monaspace font, and more.

Frontend toolchain

• fnm — Fast Node Manager
• pnpm — Fast, disk-efficient package manager
• git-cz — Conventional commits CLI

Installed file layout

After setup, your shell config looks like:

~/.zshrc                          # Thin orchestrator
~/.zshenv                         # Minimal env for non-interactive shells
~/.config/zsh/
  core/
    perf.zsh                      # Startup timing
    env.zsh                       # Environment variables
    paths.zsh                     # PATH + tool bootstrap entries
    options.zsh                   # Zsh shell options
  shared/
    tools.zsh                     # Tool init orchestrator
    tools/
      _loader.zsh                 # _load_tool_config() + version-based cache
      fzf.zsh                     # FZF env, init, Ctrl-T widget
      runtime.zsh                 # zoxide + fnm
      atuin.zsh                   # Atuin history (owns Ctrl-R)
      bun.zsh                     # Bun async completion
    plugins.zsh                   # zinit plugin declarations
    highlighting.zsh              # zsh-syntax-highlighting styles
    aliases.zsh                   # Shared aliases
    completion.zsh                # Native completion setup
    prompt.zsh                    # Prompt/theme (p10k)
  local/
    machine.zsh                   # Machine-specific overrides
    config.vim                    # Vim config
    secrets.zsh                   # API keys (create manually, gitignored)

Testing

npm test           # Run all tests
npm run test:watch # Watch mode

Tests run in sandboxed temp directories.

Implementation details and architecture notes live in AGENTS.md.

Requirements

• macOS (full support, tested on Sonoma+)
• Linux (bootstrap package-manager selection supported; most install steps still target Homebrew ecosystem)
• Node.js >= 18 for local repo usage; the curl installer bootstraps it when possible
• Zsh for local repo usage; the curl installer bootstraps it when possible
• Run suitup from a zsh session (echo $SHELL should end with zsh)

License

Apache-2.0