---
title: "Fish Shell PATH Configuration"
aliases: [fish-path, fish-user-paths, fish_add_path, fish-env]
tags: [fish, shell, path, dotfiles, terminal]
sources:
  - "daily/2026-04-15.md"
created: 2026-04-15
updated: 2026-04-15
---

# 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

```fish
# 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:

```fish
# 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:

```fish
# ~/.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

## Related Concepts

- [[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