88 lines
3.2 KiB
Markdown
88 lines
3.2 KiB
Markdown
---
|
|
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
|