Fish Shell PATH Configuration

Fish shell does not automatically include all standard system directories in PATH. Directories like /usr/local/bin are commonly missing, causing commands that work in bash to fail in Fish with Unknown command.

Key Points

/usr/local/bin is not in Fish's default PATH — tools installed there (e.g., kubectl, Homebrew binaries on older macOS installs) must be added explicitly
Use fish_add_path /usr/local/bin to permanently add a directory — it modifies fish_user_paths universal variable and persists across sessions
set -gx fish_user_paths /usr/local/bin $fish_user_paths is the older manual equivalent; fish_add_path is idempotent and preferred
spf --fix-config-file (superfile config fix) requires a live TTY and cannot run from a non-interactive context like Claude Code agent
SSH connection aliases belong in Fish functions (~/.config/fish/functions/) that wrap the underlying ~/.ssh/config entries — don't duplicate host/user/key info in Fish

Details

Adding Directories to Fish PATH

# Permanent (recommended) — idempotent, safe to run multiple times
fish_add_path /usr/local/bin
fish_add_path /opt/homebrew/bin   # Apple Silicon Homebrew

# One-time session only
set -gx PATH /usr/local/bin $PATH

# Manual permanent (older style)
set -U fish_user_paths /usr/local/bin $fish_user_paths

fish_add_path checks for duplicates, so it's safe to call in config.fish on every startup without path bloat.

Diagnosing "Unknown command" Errors

When a tool is installed but Fish can't find it:

# Find where the binary actually lives
which kubectl     # may fail
command -v kubectl

# Check current PATH
echo $PATH

# Find the binary manually
find /usr /opt /home -name kubectl 2>/dev/null

Once found, add the parent directory with fish_add_path.

SSH Aliases as Fish Functions

Wrap SSH connections in named Fish functions rather than duplicating config:

# ~/.config/fish/functions/ssh-optical.fish
function ssh-optical
    ssh optical-dev  # matches a Host block in ~/.ssh/config
end

~/.ssh/config holds the actual host, user, and identity file. The Fish function is just a convenience alias. This separation means updating the SSH config (e.g., changing a hostname) doesn't require updating Fish functions.

Dotfiles Context (2026-04-15 Setup)

Terminal stack configured to match a specific video guide style:

Terminal: Kitty
Shell: Fish + tide prompt
Editor: Neovim with kanagawa-wave theme
File manager: superfile (spf)
Font: Hasklug Nerd Font Mono, size 15

wiki/dotfiles/_index — full dotfiles topic index with Kitty, Fish, LazyVim, WezTerm articles
wiki/concepts/shell-static-deploy-patterns — other shell scripting patterns

Sources

daily/2026-04-15.md — Fish PATH fix for kubectl (/usr/local/bin not in PATH), SSH aliases setup, terminal dotfiles configuration

3.2 KiB Raw Blame History