Zsh Path

# Zsh PATH Management Skill

This skill provides comprehensive guidance for managing PATH environment variables in zsh, including troubleshooting missing commands, adding new tools, and organizing shell configuration.

## When to Use This Skill

Use this skill when:
- Getting "command not found" errors for installed tools
- Adding new tools to PATH (bun, nvm, cargo, go, Python venv, etc.)
- Validating and auditing current PATH entries
- Organizing PATH configuration between .zshrc and .zshrc.local
- Troubleshooting shell startup issues related to PATH
- Setting up version managers (nvm, pyenv, rbenv)

## Diagnostic Commands

### Check Current PATH

```bash
# List all PATH entries
echo $PATH | tr ':' '\n'

# Check if specific command is in PATH
which bun 2>/dev/null || echo "bun not found in PATH"

# Find where a command is installed
command -v node
type -a python
```

### Validate PATH Entries

```bash
# Check for broken/non-existent PATH entries
echo $PATH | tr ':' '\n' | while read p; do
  [[ -d "$p" ]] || echo "MISSING: $p"
done

# Check for duplicate PATH entries
echo $PATH | tr ':' '\n' | sort | uniq -d
```

## Common Tool PATH Configurations

### Bun (JavaScript runtime)

```bash
# Add to .zshrc
export BUN_INSTALL="$HOME/.bun"
export PATH="$BUN_INSTALL/bin:$PATH"
```

Default location: `~/.bun/bin/bun`

### NVM (Node Version Manager)

```bash
# Add to .zshrc
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"
```

Default location: `~/.nvm/`

**Note:** NVM is a shell function, not a binary. It modifies PATH dynamically to point to the active Node version.

### Python Virtual Environment

```bash
# Add to .zshrc for global tools venv
export PATH="$HOME/.venv/tools3/bin:$PATH"

# For pyenv
export PYENV_ROOT="$HOME/.pyenv"
export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init -)"
```

### Rust/Cargo

```bash
# Add to .zshrc
export PATH="$HOME/.cargo/bin:$PATH"
```

### Go

```bash
# Add to .zshrc
export GOPATH="$HOME/go"
export PATH="$GOPATH/bin:$PATH"
```

### Homebrew (macOS)

```bash
# Intel Mac
export PATH="/usr/local/bin:$PATH"

# Apple Silicon Mac
export PATH="/opt/homebrew/bin:$PATH"
eval "$(/opt/homebrew/bin/brew shellenv)"
```

### Local bin directories

```bash
# User-local binaries
export PATH="$HOME/.local/bin:$PATH"
export PATH="$HOME/bin:$PATH"
```

## File Organization Best Practices

### .zshrc (Team/Shared Configuration)

Keep in .zshrc:
- Oh My Zsh configuration
- Common team aliases
- Standard PATH additions (homebrew, local bin)
- Plugin configuration

```bash
# ===== ZSH-TOOL MANAGED SECTION BEGIN =====
# Team-wide PATH modifications
export PATH="$HOME/.local/bin:$PATH"
export PATH="$HOME/bin:$PATH"

# Bun
export BUN_INSTALL="$HOME/.bun"
export PATH="$BUN_INSTALL/bin:$PATH"

# NVM
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
# ===== ZSH-TOOL MANAGED SECTION END =====

# Load local customizations
[[ -f ~/.zshrc.local ]] && source ~/.zshrc.local
```

### .zshrc.local (Personal/Machine-Specific)

Keep in .zshrc.local:
- Machine-specific PATH entries
- Personal tool configurations
- Experimental settings
- Integrations that may override keybindings

```bash
# Machine-specific tools
export PATH="/opt/custom-tool/bin:$PATH"

# Personal integrations
if command -v atuin >/dev/null 2>&1; then
  eval "$(atuin init zsh)"
fi
```

## PATH Order Matters

PATH is searched left-to-right. First match wins.

```bash
# This order means ~/.local/bin takes priority over system bins
export PATH="$HOME/.local/bin:/usr/local/bin:/usr/bin:/bin"
```

### Recommended PATH Order

1. Project-specific bins (added by direnv)
2. User local bins (`~/.local/bin`, `~/bin`)
3. Language version managers (nvm, pyenv, rbenv)
4. Package managers (homebrew, cargo)
5. System paths (`/usr/local/bin`, `/usr/bin`)

## Troubleshooting

### Command Not Found After Installation

```bash
# 1. Find where tool was installed
ls -la ~/.bun/bin/bun 2>/dev/null
ls -la ~/.cargo/bin/rustc 2>/dev/null
ls -la ~/.nvm/versions/node/*/bin/node 2>/dev/null

# 2. Check if PATH includes the directory
echo $PATH | tr ':' '\n' | grep -E "(bun|cargo|nvm)"

# 3. Add missing PATH entry to .zshrc

# 4. Reload shell
source ~/.zshrc
# or
exec $SHELL
```

### PATH Changes Not Taking Effect

```bash
# Check which file sets the variable
grep -r "export PATH" ~/.zshrc ~/.zshrc.local ~/.zprofile 2>/dev/null

# Source the correct file
source ~/.zshrc

# Or start fresh shell
exec $SHELL
```

### Startup Hook Errors

Common causes:
- Missing PATH entries for tools used in hooks
- Broken references to non-existent directories
- Version managers not finding expected versions

```bash
# Debug startup
zsh -x 2>&1 | head -100

# Check for errors in specific config
bash -n ~/.zshrc
```

### Duplicate PATH Entries

```bash
# Remove duplicates (add to .zshrc)
typeset -U PATH path
```

## Verification Commands

After making PATH changes:

```bash
# Reload configuration
source ~/.zshrc

# Verify tool is accessible
which bun && bun --version
which node && node --version
command -v nvm && nvm --version

# Verify PATH includes new entries
echo $PATH | tr ':' '\n' | grep -E "(bun|nvm|venv)"
```

## Quick Reference

| Tool | PATH Entry | Check Command |
|------|------------|---------------|
| bun | `$HOME/.bun/bin` | `bun --version` |
| nvm | `$NVM_DIR/versions/node/*/bin` | `nvm --version` |
| cargo | `$HOME/.cargo/bin` | `cargo --version` |
| go | `$GOPATH/bin` | `go version` |
| pyenv | `$PYENV_ROOT/bin` | `pyenv --version` |
| brew (ARM) | `/opt/homebrew/bin` | `brew --version` |
| brew (Intel) | `/usr/local/bin` | `brew --version` |

## Common Patterns

### Conditional PATH Addition

```bash
# Only add if directory exists
[[ -d "$HOME/.bun/bin" ]] && export PATH="$HOME/.bun/bin:$PATH"

# Only add if command not already available
command -v bun >/dev/null || export PATH="$HOME/.bun/bin:$PATH"
```

### Lazy Loading for Faster Startup

```bash
# Lazy load nvm (faster shell startup)
lazy_load_nvm() {
  unset -f nvm node npm npx
  export NVM_DIR="$HOME/.nvm"
  [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
}
nvm() { lazy_load_nvm && nvm "$@"; }
node() { lazy_load_nvm && node "$@"; }
npm() { lazy_load_nvm && npm "$@"; }
npx() { lazy_load_nvm && npx "$@"; }
```

---

## Gotchas

- **`path=` array vs `PATH=` env var: assigning to one without `typeset -U` drops uniqueness:** Duplicates appear hours later as stale entries. Run `typeset -U path PATH` once early in `.zshrc` to bind them and dedupe automatically.
- **`.zprofile` runs only for login shells, `.zshrc` for interactive:** Homebrew's installer suggests adding `eval "$(brew shellenv)"` to `.zprofile` — non-login interactive shells (most terminal sessions on Linux) miss it entirely. Mirror to `.zshrc` if commands are missing in subshells.
- **NVM is a shell function, not a binary — `which node` lies:** After `nvm use`, `which node` shows `~/.nvm/versions/node/vXX/bin/node` but a fresh subshell may show nothing until nvm.sh is sourced again. Scripts run via `bash -c` bypass nvm entirely.
- **Lazy-loading nvm breaks `npm` invocations in shebangs:** Scripts starting with `#!/usr/bin/env node` fork a new shell, which loads `.zshrc`, which lazy-loads nvm — adding 500ms+ per script invocation. Eager-load nvm if you run many node scripts.
- **`source ~/.zshrc` doesn't undo previous PATH additions:** Re-sourcing appends without dedup, so PATH grows each time. Always start a fresh shell (`exec zsh`) when testing PATH changes, not `source`.
- **Apple Silicon Homebrew at `/opt/homebrew/bin` is invisible to Intel binaries:** Rosetta-mode terminals (`arch -x86_64 zsh`) see `/usr/local/bin` instead — same machine, two different brew prefixes, two different toolchains.