.\" Automatically generated by Pandoc 3.1.3 .\" .\" Define V font for inline verbatim, using C font in formats .\" that render this, and otherwise B font. .ie "\f[CB]x\f[]"x" \{\ . ftr V B . ftr VI BI . ftr VB B . ftr VBI BI .\} .el \{\ . ftr V CR . ftr VI CI . ftr VB CB . ftr VBI CBI .\} .TH "FISH-CONFIG" "7" "June 2026" "" "Fish Shell Configuration User Manual" .hy .SH NAME .PP fish-config - personal fish shell configuration for Fish 4.x with modern CLI tool integration .SH SYNOPSIS .IP .nf \f[C] help config [SECTION] \f[R] .fi .PP Open this manual in the best available pager. Optionally jump to a section by keyword: .IP .nf \f[C] help config keybindings help config pkg help config abbreviations help config logs \f[R] .fi .PP The \f[V]help config\f[R] syntax integrates with fish\[cq]s built-in help command. The underlying \f[V]config-help\f[R] function is also available directly. .SH DESCRIPTION .PP A production-grade Fish shell configuration targeting Fish 4.x. It provides: .IP \[bu] 2 Drop-in replacements for common Unix tools (ls, cat, rm, du, ping, less) .IP \[bu] 2 Deep Kitty and WezTerm terminal integration: tab/window/pane management from the command line .IP \[bu] 2 Automatic session logging: terminal scrollback, tmux/zellij panes, and paru/yay output captured to \[ti]/.terminal_history (on by default; see below) .IP \[bu] 2 Automatic Python virtualenv activation on directory change .IP \[bu] 2 Cross-platform package management via pkg and fish-deps .IP \[bu] 2 AI session helpers for Claude Code and Antigravity .IP \[bu] 2 Catppuccin Mocha color theme throughout .RS .PP \f[B]CAUTION - SESSION LOGGING IS ON BY DEFAULT\f[R] .PP This configuration silently records terminal output to \f[V]\[ti]/.terminal_history\f[R]: Kitty scrollback on window close, live tmux pane streams, zellij pane snapshots on exit, and full paru/yay output. These logs can contain command output, file contents, and secrets printed to the terminal. Nothing leaves your machine, but the files persist locally. .IP \[bu] 2 Disable all logging with: \f[V]set -U __fish_config_op_logging off\f[R] .IP \[bu] 2 Prefer a menu? Run the interactive picker: \f[V]config-settings\f[R] .IP \[bu] 2 See Section 7 (C5 - Logging and Capture) for the full breakdown. .RE .PP The configuration is split across: .IP .nf \f[C] config.fish Main entry point; sets env vars and PATH conf.d/ abbr.fish All abbreviations autopair.fish Auto-pair brackets and quotes (bundled from jorgebucaran/autopair.fish) cheat.fish cheat.sh tab completions done.fish Desktop notifications for long commands first_run.fish One-time init: Fisher bootstrap, theme, welcome key_bindings.fish Custom key bindings and Vi mode logging-events.fish C5 --on-variable event handlers; syncs logging state at startup kitty-watcher-reminder.fish C5 per-session reminder to set up the Kitty watcher paru-wrapper.fish Auto-generates \[ti]/.local/bin/paru logging wrapper puffer.fish !! / !$ / ./ expansion (bundled from nickeb96/puffer-fish) tmux-logging.fish C5 starts tmux pipe-pane capture when fish runs inside tmux zellij-logging.fish C5 fish_exit handler dumping zellij pane scrollback on exit sponge_privacy.fish Sponge privacy patterns; filters credentials from history starship.fish fish_prompt with OSC 133 shell-integration markers tailscale.fish Tailscale CLI tab completions theme.fish Catppuccin syntax highlight colors tricks.fish PATH, bang-bang helpers, bat man pages, aliases wakatime.fish WakaTime shell hook yay-wrapper.fish Auto-generates \[ti]/.local/bin/yay logging wrapper zoxide.fish Zoxide z/zi integration; overrides cd functions/ Custom functions, one per file, autoloaded completions/ Tab completion scripts integrations/ fzf.fish FZF Catppuccin theme and key binding config scripts/ clean_progress_log.py Strips paru/yay typescript animations to clean static logs agents-tools/ AGENTS.md version-bump script and git hooks (wired via core.hooksPath) docs/ Offline documentation and compiled man page fish-config.md Primary source manual (terminal-readable) fish-config.1 Compiled man page (auto-generated by CI) fish-config.index Section index for help config navigation html/ Chunked HTML docs (auto-generated by CI) wiki/ Markdown wiki (auto-generated by CI) \f[R] .fi .PP * * * * * .SH TABLE OF CONTENTS .IP .nf \f[C] 1. Configuration Variables 2. PATH Setup 3. Key Bindings 4. Abbreviations 4.1 Editors 4.2 Navigation and Listing 4.3 Git 4.4 Terminal Windows, Tabs, and Panes 4.5 Chezmoi 4.6 Docker 4.7 Systemctl 4.8 AI Assistants 4.9 History Expansion 4.10 Miscellaneous 4.11 Shell Aliases 5. Functions Reference 5.1 File and Directory 5.2 Navigation 5.3 Editors and Viewers 5.4 Git and Version Control 5.5 Package Management 5.6 Dependency Management 5.7 System and Monitoring 5.8 Terminal Management 5.9 Clipboard 5.10 Network 5.11 Pager and Logging 5.12 AI and Developer Tools 5.13 Media and Utilities 5.14 Miscellaneous 6. Dependency Catalog 7. Customization 8. Fisher Plugins 9. Installation 10. Personalization 11. Viewing This Manual \f[R] .fi .PP * * * * * .SH 1. CONFIGURATION VARIABLES .PP These variables are exported from config.fish on every interactive session. Override them in local.fish (see Section 10, Personalization). .SS Environment Directories (XDG) .IP .nf \f[C] XDG_CONFIG_HOME \[ti]/.config XDG_CACHE_HOME \[ti]/.cache XDG_DATA_HOME \[ti]/.local/share XDG_STATE_HOME \[ti]/.local/state \f[R] .fi .PP Tools that respect XDG are directed to these paths rather than polluting $HOME. .SS Tool Homes (XDG-compliant) .IP .nf \f[C] CARGO_HOME $XDG_DATA_HOME/cargo RUSTUP_HOME $XDG_DATA_HOME/rustup GOPATH $XDG_DATA_HOME/go BUN_INSTALL $XDG_DATA_HOME/bun NPM_CONFIG_PREFIX $XDG_DATA_HOME/npm-global GNUPGHOME $XDG_CONFIG_HOME/gnupg WAKATIME_HOME $XDG_CONFIG_HOME/wakatime \f[R] .fi .SS Editor and Pager .IP .nf \f[C] EDITOR nvim (falls back to vi if nvim is absent) VISUAL unset by default; set a GUI editor via local.fish (the edit function falls back to a GUI chain when VISUAL is empty) SUDO_EDITOR same as EDITOR PAGER ov (falls back to less) \f[R] .fi .SS Scrollback History .IP .nf \f[C] __fish_scrollback_history_dir (unset → \[ti]/.terminal_history) __fish_scrollback_history_max_files (unset → 100) SCROLLBACK_HISTORY_DIR \[ti]/.terminal_history (exported mirror) SCROLLBACK_HISTORY_MAX_FILES 100 (exported mirror) \f[R] .fi .PP The __fish_scrollback_history_* universal variables are the fish-style source of truth \[em] set them via \f[V]config-settings\f[R] → Paths, or \f[V]set -U\f[R] directly. config.fish exports the SCROLLBACK_HISTORY_* mirrors from them, because the POSIX wrapper scripts (paru/yay/tmux/zellij logging and _prune_terminal_logs) read the exported names from the environment. When the __fish_ vars are unset, the documented defaults are exported. config.fish deliberately does not create a global source var, which would shadow the universal and stop live edits from taking effect. .PP Scrollback logs accumulate in SCROLLBACK_HISTORY_DIR as timestamped files. When the count exceeds SCROLLBACK_HISTORY_MAX_FILES the oldest are pruned automatically on exit. Use \f[V]logs\f[R] to browse them interactively. .SS Other .IP .nf \f[C] GPG_TTY $(tty) \[em] ensures GPG passphrase prompts work CLAUDE_CODE_NO_FLICKER 1 \[em] suppress terminal flicker in Claude Code CDPATH . \[ti]/projects \[ti] \f[R] .fi .PP Opinionated defaults (CDPATH, PAGER/MANPAGER, Vi mode, command shadows, terminal integrations) can be switched off per category with universal variables \[em] see Section 7, \[lq]Opinionated Components (Minimal Mode)\[rq]. .SS Pager Hierarchy .PP $PAGER is set to ov when available, falling back to less. The less wrapper function extends this into a full chain so anything that calls less directly also benefits: .IP .nf \f[C] $PAGER → ov → less → more → cat \f[R] .fi .PP When bat is installed, man pages are rendered with syntax highlighting: .IP .nf \f[C] MANROFFOPT -c MANPAGER sh -c \[aq]col -bx | bat -l man -p\[aq] \f[R] .fi .SS Integrations .SS Zoxide .PP cd, z, and cdi/zi are all mapped to zoxide-backed navigation. Tab completions for cd and z blend standard directory entries (CWD and CDPATH) with frecency results so both familiar and frequently-visited paths appear in one list. .SS DirEnv .PP Automatically loads .envrc files on directory change. Takes priority over the auto-venv logic \[em] if a directory is managed by direnv, the auto-venv activation is skipped entirely. .SS Auto Python Venv .PP When entering a directory that contains a .venv/, the virtualenv is activated automatically and deactivated when you leave the project tree. .SS WakaTime .PP Every shell command is reported to WakaTime for time-tracking. Set FISH_WAKATIME_DISABLED=1 to disable without removing the plugin. .SS Tailscale .PP Full tab completion for the tailscale CLI is provided via conf.d/tailscale.fish. .SS Done Notifications .PP Desktop notifications fire when a command takes longer than 10 seconds and the terminal window is not focused. Configured via fish universal variables: .IP .nf \f[C] __done_min_cmd_duration 10000 ms __done_notification_urgency_level low \f[R] .fi .SS Scrollback History .PP When running inside Kitty, closing a shell session via exit saves a timestamped scrollback snapshot to SCROLLBACK_HISTORY_DIR. Files are named: .IP .nf \f[C] scrollback_YYYY-MM-DD_HH-MM-SS.log \f[R] .fi .PP The paru and yay wrappers (auto-generated in \[ti]/.local/bin/) run the command inside a PTY via script(1) so download progress bars are preserved on screen, then render the captured terminal animation down to a clean static log via scripts/clean_progress_log.py (a small terminal-screen emulator that replays cursor movements, collapses repainted progress frames to their final state, and preserves ANSI color). If python3 is unavailable the wrapper falls back to dropping only the script(1) header/footer. Output is saved to: .IP .nf \f[C] paru_YYYY-MM-DD_HH-MM-SS.log yay_YYYY-MM-DD_HH-MM-SS.log \f[R] .fi .PP Before pruning, _scrollback_prune_junk silently removes empty files, files with only a single meaningful line (e.g.\ bare [exited] captures), and Kitty tab-rename prompt captures. Use exit \[en]no-log (or exit -n) to skip capture. .PP * * * * * .SH 2. PATH SETUP .PP Directories prepended to PATH in this order (first wins): .IP .nf \f[C] \[ti]/.local/bin Standard user-local executables \[ti]/Applications User-installed standalone apps \[ti]/scripts Personal shell scripts \[ti]/bin Cargo binaries (appended \[em] lowest priority) $BUN_INSTALL/bin Bun runtime and global packages $NPM_CONFIG_PREFIX/bin Global npm packages \[ti]/.lmstudio/bin LM Studio CLI \[ti]/.resend/bin Resend CLI \[ti]/.fzf/bin fzf binary (git-installed) \f[R] .fi .PP Cargo binaries are intentionally appended (lowest priority) to avoid shadowing system-installed Rust tools. .PP * * * * * .SH 3. KEY BINDINGS .PP The shell uses Vi key bindings (fish_vi_key_bindings). All custom bindings are active in Insert, Normal, and Visual modes unless noted. .IP .nf \f[C] Binding Action ───────────────────────────────────────────────────────────────────── Ctrl+G Insert the head of the previous command\[aq]s last path argument. Equivalent to !$:h in Bash. Example: previous = \[dq]cd /usr/local/bin\[dq] Ctrl+G inserts \[dq]/usr/local\[dq] Ctrl+F Interactive history substitution. Type old/new then press Ctrl+F to apply s/old/new/ to the previous command. Equivalent to !!:s/old/new/ in Bash. Example: previous = \[dq]echo this is a test\[dq] type \[dq]this is/that was\[dq], press Ctrl+F result = \[dq]echo that was a test\[dq] Ctrl+Alt+U Strip the first token of the current command line, leaving arguments in place with the cursor at the start. Useful for quickly retyping the command. Example: \[dq]mkdir new_folder\[dq] -> \[dq] new_folder\[dq] Ctrl+Alt+= Evaluate the current command line buffer with Qalculate! (qalc) and print the result inline. Requires qalc to be installed. Example: type \[dq]150 * 1.08\[dq], press Ctrl+Alt+= prints 162 Ctrl+Enter Smart execute: runs commands instantly without pressing Enter a second time for certain fast-path commands (speedtest-fast, etc.). \[at]\[at] FZF inline picker. Type \[at]\[at] anywhere on the command line to open an fzf picker and insert a selection at the cursor position. \f[R] .fi .SS FZF Bindings (bundled from PatrickF1/fzf.fish) .IP .nf \f[C] Ctrl+R Search command history Ctrl+Alt+F Search git-tracked files Ctrl+Alt+L Search git log Ctrl+Alt+S Search git status Ctrl+V Search shell variables Ctrl+Alt+P Search running processes \f[R] .fi .PP * * * * * .SH 4. ABBREVIATIONS .PP Abbreviations expand when you press Space or Enter. They are terminal-aware: some expand differently in Kitty vs WezTerm vs other terminals. .SS 4.1 Editors .IP .nf \f[C] n / nv / neovim nvim e edit se sudoedit k kate editt Open new tab with nvim (terminal-aware) cdnv cd \[ti]/.config/nvim cdnvn cd \[ti]/.config/nvim; nvim \f[R] .fi .SS 4.2 Navigation and Listing .IP .nf \f[C] l ls lS lss (sort by size) lsR lsr (sort by time, oldest first) lX lx (sort by extension) lT lt (tree, depth 2) lsT lstree (full recursive tree) lzd ld (lazydocker) cdi zi (interactive zoxide picker) \f[R] .fi .SS 4.3 Git .IP .nf \f[C] g git lg lazygit gitig / git-ignore gi (generate .gitignore) \f[R] .fi .SS 4.4 Terminal Windows, Tabs, and Panes .PP These abbreviations control the terminal emulator. Each has a Kitty variant and a WezTerm variant; the correct one is inserted based on $TERM or $TERM_PROGRAM. .IP .nf \f[C] :w New OS window :wv Split pane horizontally (new pane below) :wh Split pane vertically (new pane to the right) :wo Detach current window to its own OS window :wot Move current pane to a new tab :t New tab :tl Set tab title :tw Set window title :twk Rename workspace (WezTerm only) :tp Focus previous tab :tn Focus next tab :q Close current pane/window :Q Close current tab :sw spwin (spawn new OS window) \f[R] .fi .PP Quick-navigate shortcuts open windows/tabs/panes with preset working dirs: .IP .nf \f[C] :tgk New tab at \[ti]/.config/kitty :tgn New tab at \[ti]/.config/nvim :tgf New tab at \[ti]/.config/fish :tgh New tab at \[ti] :tgcz New tab at chezmoi source dir :tgcm New tab at chezmoi source dir :tgp New tab at \[ti]/projects :tgr New tab at / (root) \f[R] .fi .PP Prefixes :wg* and :wvg* / :whg* open OS windows or splits to the same set of dirs, respectively. .PP Prefixes :cd* open tabs with a quick cd shortcut: .IP .nf \f[C] :cdn cd \[ti]/.config/nvim :cdf cd \[ti]/.config/fish :cdh cd \[ti] :cdcz cd to chezmoi source :cdp cd \[ti]/projects \f[R] .fi .PP Appending n to any :cd* abbreviation also runs nvim after changing dir. .SS 4.5 Chezmoi .IP .nf \f[C] cm / cme / cmi / cmap / cmad / cmrm / cmcd / cz / cze / czi / czap / czad / czrm / czcd cm / cz chezmoi cmcd / czcd chezmoi cd cme / cze chezmoi edit cmad / czad chezmoi add cmap / czap chezmoi apply cmrm / cmf / czrm / czf chezmoi forget cmi / czi chezmoi init \f[R] .fi .SS 4.6 Docker .IP .nf \f[C] dcl docker context use default dcls docker context ls lzd ld (lazydocker) \f[R] .fi .SS 4.7 Systemctl .IP .nf \f[C] sc systemctl ssc sudo systemctl scu systemctl --user st systemctl status scs sudo systemctl start scr sudo systemctl restart ssct sudo systemctl start sscs sudo systemctl stop sscr sudo systemctl restart \f[R] .fi .SS 4.8 AI Assistants .IP .nf \f[C] ag agy ag. agy . v antigravity-ide s wezterm ssh (WezTerm only) \f[R] .fi .SS 4.9 History Expansion .PP These are implemented as keybinding helpers, but can also be typed: .IP .nf \f[C] !\[ha] Expand to first argument of previous command !* Expand to all arguments of previous command typo_sub Interactive typo substitution (Ctrl+F) bang_string !string expansion bang_search !?string search bang_minus_n !-n (nth-previous command) \f[R] .fi .SS 4.10 Miscellaneous .IP .nf \f[C] /exit exit :q Close pane (alias for terminal close) :Q Close tab sudu sudo -s kt kitty (Kitty only) c cat speedtest-fast fast-cli bl bd list bs bd sync bC bd create --title bsh bd show lb lazybeads \f[R] .fi .SS 4.11 Shell Aliases .PP These aliases are defined in conf.d/tricks.fish via alias (which creates Fish functions). They are active in all interactive sessions. .SS Navigation .IP .nf \f[C] \&.. cd .. \&... cd ../.. \&.... cd ../../.. \&..... cd ../../../.. \&...... cd ../../../../.. \f[R] .fi .SS Color Overrides .PP Force color output for common tools: .IP .nf \f[C] grep grep --color=auto fgrep fgrep --color=auto egrep egrep --color=auto dir dir --color=auto vdir vdir --color=auto \f[R] .fi .SS Safety Wrappers .PP Add -i (interactive confirmation) to destructive commands: .IP .nf \f[C] cp cp -i mv mv -i \f[R] .fi .SS Archives and Networking .IP .nf \f[C] tarnow tar -acf Create compressed archive (auto-detects format) untar tar -zxvf Extract a gzip-compressed archive wget wget -c Resume interrupted downloads by default tb nc termbin.com 9999 Pipe content to termbin.com for quick sharing \f[R] .fi .SS System Logs .IP .nf \f[C] jctl journalctl -p 3 -xb Show priority-3 (error) journal entries from the current boot \f[R] .fi .PP * * * * * .SH 5. FUNCTIONS REFERENCE .SS 5.1 File and Directory .SS cat .IP .nf \f[C] Synopsis: cat [args...] Wraps bat for files with syntax highlighting and line numbers. Passes directories to ls. Falls back to /usr/bin/cat. cat README.md cat \[ti]/projects/myapp \f[R] .fi .SS copy .IP .nf \f[C] Synopsis: copy Wraps cp, stripping trailing slashes from source directories to prevent unintended nesting inside the destination. copy ./mydir/ \[ti]/backup # copies mydir INTO backup, not backup/mydir/ \f[R] .fi .SS du .IP .nf \f[C] Synopsis: du [--disk|--dir|--dua] [args...] Smart disk-usage dispatcher: --disk force duf (disk-level free/used overview) --dir force dust (per-directory tree breakdown) --dua force dua (fast space analyzer) Without flags, routes to the most appropriate tool by context. du \[ti]/Downloads du --disk \f[R] .fi .SS dusize .IP .nf \f[C] Synopsis: dusize [dir] Human-readable disk usage for a directory via du -sh. Defaults to cwd. dusize \[ti]/Videos \f[R] .fi .SS lD .IP .nf \f[C] Synopsis: lD [args...] Lists directories only in long format with icons. Uses eza, falls back to lsd, then system ls. lD \[ti]/projects \f[R] .fi .SS ls .IP .nf \f[C] Synopsis: ls [args...] Lists files in long format with icons and hyperlinks. Uses eza, falls back to lsd, then system ls. ls ls -a \[ti]/projects \f[R] .fi .SS lsr .IP .nf \f[C] Synopsis: lsr [args...] Lists files sorted by modification time, oldest first. Uses eza. \f[R] .fi .SS lss .IP .nf \f[C] Synopsis: lss [args...] Lists files sorted by size with gradient color scaling. Uses eza. \f[R] .fi .SS lstree .IP .nf \f[C] Synopsis: lstree [args...] Full recursive tree view with icons. Uses eza. lstree \[ti]/projects/myapp \f[R] .fi .SS lt .IP .nf \f[C] Synopsis: lt [args...] Tree view limited to depth 2 with icons. Uses eza. lt \[ti]/projects \f[R] .fi .SS ltr .IP .nf \f[C] Synopsis: ltr [args...] Lists files sorted by modification time, oldest first, long format with age-based gradient scaling. Uses eza. \f[R] .fi .SS lx .IP .nf \f[C] Synopsis: lx [args...] Lists files sorted by extension, long format. Uses eza. \f[R] .fi .SS mkdir .IP .nf \f[C] Synopsis: mkdir [args...] Interactive mkdir that prints a tree of created directories. Falls back to mkdir -p silently. mkdir \[ti]/projects/myapp/src \f[R] .fi .SS mkcd .IP .nf \f[C] Synopsis: mkcd [-s] Creates a directory (including parents) and cd into it. Prints a tree of created dirs by default; -s/--silent suppresses output. mkcd \[ti]/projects/newapp/src \f[R] .fi .SS poke .IP .nf \f[C] Synopsis: poke [file...] Creates files via touch, automatically creating any missing parent directories first. poke \[ti]/projects/new/src/main.fish \f[R] .fi .SS rm .IP .nf \f[C] Synopsis: rm [-e [opts] | -S | args...] Safe rm wrapper routing to trash: (no args) List current trash contents -e/--empty Empty the trash (pass options to trash-empty) -S/--secure Permanently delete via rm -rf + fstrim (irreversible) -r/-R/--recursive Move to trash Move to trash (safe delete) Falls back to /usr/bin/rm when trash is unavailable. rm file.txt # moves to trash rm -e # empty trash rm -S sensitive.pem # permanent delete \f[R] .fi .SS rg .IP .nf \f[C] Synopsis: rg [args...] In Kitty, wraps ripgrep with --hyperlink-format=kitty so search results are clickable file links in the terminal. Falls back to system rg in any other terminal. All other arguments pass through unchanged. rg \[dq]fish_greeting\[dq] \[ti]/.config/fish/ rg -l \[dq]TODO\[dq] \[ti]/projects/myapp \f[R] .fi .SS scrub .IP .nf \f[C] Synopsis: scrub [-a] [-d] [-h] Recursively removes OS metadata, editor artifacts, compiler output, and dev caches using fd. -a/--aggressive Also removes node_modules, logs, .cache, IDE dirs, AI session artifacts -d/--dry-run Print what would be removed without deleting scrub scrub -a scrub -d \f[R] .fi .PP * * * * * .SS 5.2 Navigation .SS cdi .IP .nf \f[C] Synopsis: cdi [query] Interactive directory picker combining zoxide frecency with fzf. Equivalent to zi. cdi myproject \f[R] .fi .SS clone .IP .nf \f[C] Synopsis: clone [args...] Clone a git repository into a new Kitty window. Kitty-only. clone https://github.com/user/repo.git \f[R] .fi .SS clonet .IP .nf \f[C] Synopsis: clonet [args...] Clone a git repository into a new Kitty tab. Kitty-only. clonet https://github.com/user/repo.git \f[R] .fi .PP * * * * * .SS 5.3 Editors and Viewers .SS edit .IP .nf \f[C] Synopsis: edit [-V|-t] [-e EDITOR] [-c] [-x TEXT] [-n] [-v|-s] [FILE...] Opens files in a text editor, choosing a terminal or GUI editor and resolving a rich chain of fallbacks. With no --visual/--terminal flag the mode is auto-detected: interactive terminals use the terminal editor ($EDITOR), while detached invocations (e.g. desktop shortcuts) use the GUI editor ($VISUAL). Clipboard contents and literal strings can be opened as throwaway temp files. Editor output is suppressed unless --verbose. GUI fallback chain: zed → antigravity-ide → code → kate → kwrite → gnome-text-editor → gedit Terminal fallback chain: nvim → vim → micro → nano → vi Options: -V, --visual Force the GUI editor ($VISUAL or fallbacks) -t, --terminal Force the terminal editor ($EDITOR or fallbacks) -e, --editor=X Use a specific editor binary X -c, --clipboard Open the clipboard contents (as a temp file) -x, --text=STR Open STR as the contents of a new temp file -n, --new Force a new window/instance (best-effort) -v, --verbose Print the launch command and editor output -s, --silent Suppress all output, including the editor\[aq]s -h, --help Show this help message edit \[ti]/.config/fish/config.fish edit --visual notes.txt edit --terminal --new todo.md edit --editor=code --clipboard edit --text=\[dq]hello world\[dq] \f[R] .fi .SS fc .IP .nf \f[C] Synopsis: fc [command_prefix] Edit the last shell command (or one matching a prefix) in $EDITOR, then execute the result. Bash-style fc behaviour. fc fc git \f[R] .fi .SS less .IP .nf \f[C] Synopsis: less [args...] Pager wrapper with fallback chain: $PAGER -> ov -> less -> more -> cat. less /var/log/syslog \f[R] .fi .SS rawfish .IP .nf \f[C] Synopsis: rawfish [args...] Launches Fish with NO_TMUX=1, bypassing any tmux auto-attach logic. Useful when you need a clean shell without session management. \f[R] .fi .SS view .IP .nf \f[C] Synopsis: view [args...] Opens files in nvim read-only mode (-R). Falls back to less. view /etc/fstab \f[R] .fi .PP * * * * * .SS 5.4 Git and Version Control .SS auto-pull .IP .nf \f[C] Synopsis: auto-pull [list] auto-pull add [PATH] auto-pull remove auto-pull status Manages the registry of repositories that are background fast-forwarded when you enter them (see \[dq]Auto-pull fast-forward\[dq] under the C2 component reference). The fish-config repo is always covered as a baseline. The registry is machine-local at \[ga]$__fish_user_dots_path/auto-pull.list\[ga] (defaults to \[ga]\[ti]/.config/.user-dots/fish/auto-pull.list\[ga]), one absolute path per line, and is never committed. Registry management works even when C2 auto-execution is disabled; only the background sync is gated. list Show registered repos (default) add [PATH] Register PATH\[aq]s git root (default: current repo) remove Unregister by basename or exact path status Show enabled/disabled state, repo count, list path cd \[ti]/src/qmk_firmware; and auto-pull add auto-pull add \[ti]/work/api auto-pull list auto-pull remove qmk_firmware \f[R] .fi .SS branch .IP .nf \f[C] Synopsis: branch Switches to a local branch, or creates it if it does not exist. branch feature/new-ui \f[R] .fi .SS gi .IP .nf \f[C] Synopsis: gi [-h] [-b] [-p] [-s] [-l] [targets...] Generates .gitignore content from the gitignore.io API with MD5-based deduplication (patterns already present are not re-appended). -b/--boilerplate Append generic boilerplate first -p/--prompt Prompt interactively for targets -s/--stdout Print to stdout instead of appending to .gitignore -l/--list List all available targets targets Comma-separated or space-separated target names gi python,venv gi -b -p gi -s node > .gitignore \f[R] .fi .SS git-clean .IP .nf \f[C] Synopsis: git-clean [-f] Fetches and prunes the remote, fast-forwards the current branch, then deletes local branches whose remote tracking branch has been deleted. Switches to main/master automatically if the current branch is orphaned. -f/--force Force-delete unmerged branches too git-clean git-clean --force \f[R] .fi .SS gitup .IP .nf \f[C] Synopsis: gitup [args...] Fetches updates from the remote and shows git status. Extra args are forwarded to git fetch. gitup gitup --all \f[R] .fi .SS gitui .IP .nf \f[C] Synopsis: gitui [args...] Launches gitui with the Catppuccin Frappe theme pre-applied. \f[R] .fi .SS hist .IP .nf \f[C] Synopsis: hist Searches shell history with fzf, inserts the selection into the command line, and copies it to the clipboard via wl-copy. \f[R] .fi .PP * * * * * .SS 5.5 Package Management .SS pkg .IP .nf \f[C] Synopsis: pkg [-h] [-i|-u] [package...] Installs or removes packages using the detected system package manager. Supports: paru, yay, pacman, apt, dnf, zypper, yum, brew, pkg. (no flag) Auto mode: installs missing packages, removes installed ones -i/--install Force install -u/--uninstall Force uninstall pkg firefox # auto: install if missing, remove if present pkg -i ripgrep fd # force install pkg -u cowsay # force uninstall The package-installed check uses the correct query for each PM: pacman/paru/yay pacman -Qi apt dpkg -s dnf/zypper/yum rpm -q brew brew list pkg pkg info \f[R] .fi .SS search .IP .nf \f[C] Synopsis: search [args...] Interactive AUR package search and install via paru or yay. Arch Linux only. search neovim \f[R] .fi .SS upgrade .IP .nf \f[C] Synopsis: upgrade Full system upgrade via paru -Syu --noconfirm or yay -Syu --noconfirm. Arch Linux only. \f[R] .fi .SS cleanup .IP .nf \f[C] Synopsis: cleanup Lists and removes orphan packages via pacman, logging their names to \[ti]/.removed_orphans. Arch Linux only. \f[R] .fi .SS parur .IP .nf \f[C] Synopsis: parur Opens an fzf picker of all installed packages (with pacman -Qi previews), then removes the selected packages via paru or yay. Arch Linux only. parur \f[R] .fi .PP * * * * * .SS 5.6 Dependency Management .SS fish-deps .IP .nf \f[C] Synopsis: fish-deps [status|install|update|sync] Unified command for managing all tools this configuration depends on. status (default) Show installed/missing status grouped by tier install Interactively install each missing dependency update Update all installed dependencies sync Install missing deps, then update all Install method priority (highest to lowest): 1. git+cargo source build (fish shell itself) 2. cargo (Rust tools \[em] gets latest crate version) 3. system PM (paru/apt/brew/etc.) 4. git clone (fzf) 5. curl installer (starship, fisher, uv) When multiple methods are available you are prompted to choose. Dependencies are grouped into three tiers: Required fish, fzf, zoxide Integrations wakatime, tailscale Recommended cargo, starship, uv, direnv, paru, yay, eza, lsd, bat, btop, dust, duf, prettyping, ov, ripgrep, lazygit, lazydocker, trash, kitty, wezterm, python3, yt-dlp fish-deps fish-deps install fish-deps update fish-deps sync \f[R] .fi .SS check_fish_deps .IP .nf \f[C] Synopsis: check_fish_deps Backwards-compatibility alias for \[ga]fish-deps status\[ga]. \f[R] .fi .PP * * * * * .SS 5.7 System and Monitoring .SS top .IP .nf \f[C] Synopsis: top [args...] Launches btop as a modern resource monitor. Falls back to system top. \f[R] .fi .SS swapstat .IP .nf \f[C] Synopsis: swapstat Displays a colorized memory report: kernel swappiness, zRAM compression ratio, zRAM device details, and active swap priorities. \f[R] .fi .SS sbver .IP .nf \f[C] Synopsis: sbver [--brief] Verifies Secure Boot signatures on all EFI binaries tracked by sbctl. Color-codes results: green checkmark (verified), red X (unsigned). Prints a pass/fail summary. --brief Suppress per-file output, show only the summary sbver sbver --brief \f[R] .fi .SS ports .IP .nf \f[C] Synopsis: ports Lists active TCP listeners with lsof, showing port/address without hostname resolution. \f[R] .fi .SS screensleep .IP .nf \f[C] Synopsis: screensleep Turns off the display via KDE PowerDevil\[aq]s \[dq]Turn Off Screen\[dq] action, invoked through busctl. \f[R] .fi .SS lock .IP .nf \f[C] Synopsis: lock Locks the current desktop session using loginctl lock-session. \f[R] .fi .SS sudo-toggle .IP .nf \f[C] Synopsis: sudo-toggle Toggles the sudo NOPASSWD rule on/off via /etc/sudoers.d/nofail-toggle. Useful for automated tasks that would otherwise require password entry. \f[R] .fi .SS limine-edit .IP .nf \f[C] Synopsis: limine-edit Opens /boot/limine.conf in sudoedit, then automatically re-enrolls the config hash, runs CachyOS boot hooks, and re-signs Secure Boot files. Combines the edit and sign steps into a single command. \f[R] .fi .PP * * * * * .SS 5.8 Terminal Management .SS tab .IP .nf \f[C] Synopsis: tab [args...] Opens a new tab in Kitty (kitty \[at] launch --type=tab), WezTerm (wezterm cli spawn), or Konsole. Uses current working directory, or $cdto if set. tab \f[R] .fi .SS split .IP .nf \f[C] Synopsis: split [-h|-v] [command...] Opens a new pane in Kitty or WezTerm, optionally running a command. -h/--horizontal (default) Split below -v/--vertical Split to the right split split -v nvim README.md \f[R] .fi .SS spwin .IP .nf \f[C] Synopsis: spwin [args...] Spawns a new terminal OS window in Kitty (via spawn-window.sh or kitty \[at] launch --type=os-window) or WezTerm (wezterm cli spawn --new-window). \f[R] .fi .SS detach .IP .nf \f[C] Synopsis: detach [-h] [--version] [args...] Runs a command fully detached via nohup with stdout/stderr discarded. The command survives the current session. detach rsync -a ./data remote:/backup/ \f[R] .fi .SS bkg .IP .nf \f[C] Synopsis: bkg [args...] Launches a command in the background via nohup with output discarded. Simpler than detach; no version flag. bkg firefox \f[R] .fi .SS ssh .IP .nf \f[C] Synopsis: ssh [args...] In Kitty, wraps ssh with kitten ssh for better terminal integration (multiplexing, copy/paste support). Falls back to system ssh elsewhere. ssh user\[at]host \f[R] .fi .PP * * * * * .SS 5.9 Clipboard .SS y .IP .nf \f[C] Synopsis: y [text...] Copies text to the clipboard via wl-copy (Wayland) or xclip (X11). Reads from stdin if no arguments given. y \[dq]hello world\[dq] ls | y cat file.txt | y \f[R] .fi .SS p .IP .nf \f[C] Synopsis: p [args...] Outputs clipboard contents to stdout. p | grep foo p > file.txt \f[R] .fi .SS paste .IP .nf \f[C] Alias for p. Identical behaviour. \f[R] .fi .PP * * * * * .SS 5.10 Network .SS gip .IP .nf \f[C] Synopsis: gip Fetches and prints both the public IPv4 and IPv6 address via icanhazip.com. \f[R] .fi .SS gip4 .IP .nf \f[C] Synopsis: gip4 Fetches and prints the public IPv4 address. \f[R] .fi .SS gip6 .IP .nf \f[C] Synopsis: gip6 Fetches and prints the public IPv6 address. Returns 1 if IPv6 is unavailable. \f[R] .fi .SS ping .IP .nf \f[C] Synopsis: ping [args...] Wraps prettyping with --nolegend. Pass --legend to show the legend. Falls back to system ping. ping google.com \f[R] .fi .SS qr .IP .nf \f[C] Synopsis: qr [text...] Generates a UTF-8 QR code from text or stdin. Uses qrencode locally; falls back to the qrenco.de API. qr \[dq]https://example.com\[dq] echo \[dq]https://example.com\[dq] | qr \f[R] .fi .PP * * * * * .SS 5.11 Pager and Logging .SS logs .IP .nf \f[C] Synopsis: logs [-c ] Interactively browses terminal log files sorted newest-first using fzf. -c/--category Filter to: scrollback, paru, or yay Keybindings inside the fzf browser: Enter Open in $PAGER Ctrl+E Open in $EDITOR Ctrl+D Delete (with confirmation) ? Toggle keybind help overlay Paru and yay logs open in ov with syntax highlighting and sticky section headers. Scrollback logs open in ov with per-command sticky prompt headers based on OSC 133 markers. logs logs -c paru logs -c scrollback \f[R] .fi .SS smart_exit .IP .nf \f[C] Synopsis: smart_exit [-n] Closes the shell session. In Kitty, captures the terminal scrollback to a timestamped log file in $SCROLLBACK_HISTORY_DIR before exiting. Automatically prunes the oldest logs when the count exceeds $SCROLLBACK_HISTORY_MAX_FILES. -n/--no-log Exit without saving a scrollback log The exit builtin is wired to smart_exit for interactive sessions. Typing exit or Ctrl+D behaves identically to smart_exit. smart_exit smart_exit --no-log \f[R] .fi .PP * * * * * .SS 5.12 AI and Developer Tools .SS agy .IP .nf \f[C] Synopsis: agy [args...] Wrapper for the agy Antigravity AI CLI. Before launching, delegates to agents-init --agents to ensure AGENTS/ is scaffolded and CLAUDE.md is symlinked to AGENTS/AGENTS.md in the current project, then forwards all arguments verbatim to the real agy binary. Command shadow (C1): when __fish_config_op_aliases (or the master) is disabled, the call is passed through to the real agy binary unchanged. agy chat agy resume \f[R] .fi .SS antigravity-ide .IP .nf \f[C] Synopsis: antigravity-ide [args...] Runs the antigravity-ide editor with warnings filtered. \f[R] .fi .SS agents-init .IP .nf \f[C] Synopsis: agents-init [--agents | --plugins] Scaffold an AGENTS/ sub-repository for tracking agent specs, plans, specs, and dev logs. Creates AGENTS/ as a standalone git repo, moves any existing AGENTS.md into it, and replaces it with a relative symlink (plus CLAUDE.md -> AGENTS/AGENTS.md so Claude Code picks up the shared agent instructions). Consolidates plans/ and specs/ directly under AGENTS/ (merging any legacy docs/plans, docs/superpowers/plans, or old AGENTS/plugins/ locations into the canonical AGENTS/), creates AGENTS/devlogs/, and wires docs/superpowers/{plans,specs} symlinks back to them. Adds managed paths to .gitignore and auto-commits every change inside the AGENTS/ sub-repo; pulls first when the sub-repo has an upstream. Fully idempotent: a second run produces no output and no new commits. Flags: --agents re-runs only the AGENTS.md / symlink step; --plugins re-runs only the plans/specs/devlogs wiring step. Called automatically by the claude and agy wrappers on every invocation. Structure versioning: each AGENTS/ repo carries a self-contained version bumper. AGENTS/.version holds MAJOR.MINOR.PATCH (seeded 1.0.0). Committed git hooks under AGENTS/.agents-tools/ (wired via core.hooksPath) bump it on every commit: MINOR (resetting PATCH) when the tracked directory set changes, PATCH otherwise; MAJOR is manual-only. A prepare-commit-msg hook appends \[dq](vX.Y.Z)\[dq] to the commit subject. Downstream tooling can read AGENTS/.version - a changed MINOR field signals a structure change. Because core.hooksPath is a single setting, the local override would otherwise shadow your global hooks; after bumping the version, each shim chains (execs) to the global/system core.hooksPath hook of the same name so global pre-commit / prepare-commit-msg hooks (e.g. ggshield, Git LFS) still run. The script and hooks are shipped from scripts/agents-tools/ and refreshed when their version marker is stale. agents-init agents-init --agents agents-init --plugins \f[R] .fi .SS claude .IP .nf \f[C] Synopsis: claude [args...] Wrapper for the claude CLI. Before launching, delegates to agents-init --agents to ensure AGENTS/ is scaffolded and CLAUDE.md is symlinked to AGENTS/AGENTS.md in the current project, then forwards all arguments verbatim to the real claude binary. Command shadow (C1): when __fish_config_op_aliases (or the master) is disabled, the call is passed through to the real claude binary unchanged. claude claude --resume \f[R] .fi .SS claude-docs .IP .nf \f[C] Synopsis: claude-docs Invokes Claude Code to analyze recent repository changes and update README.md, ensuring all documented features and examples are accurate. \f[R] .fi .SS claude-pr .IP .nf \f[C] Synopsis: claude-pr Invokes Claude Code to run the full PR workflow: create branch, conventional commit, verification, push, and open a PR with a manual verification checklist. \f[R] .fi .SS superpowers .IP .nf \f[C] Synopsis: superpowers [on|off] [-g] Enables or disables the Superpowers plugin for Antigravity and Claude Code at workspace/project scope (default) or user scope (-g/--global). superpowers on superpowers off -g \f[R] .fi .PP * * * * * .SS 5.13 Media and Utilities .SS dng2avif .IP .nf \f[C] Synopsis: dng2avif [-i ] [-o ] [-q ] [-s ] [input.dng] Converts a DNG raw image to a 10-bit HDR AVIF using an ImageMagick, ffmpeg, avifenc pipeline with metadata sync via exiftool. -i/--input Input file (or positional arg) -o/--output Output file (default: same name, .avif extension) -q/--quality Quality 0-100 (default 92) -s/--speed Encoding speed 0-10 (default 3) dng2avif photo.dng dng2avif -q 85 -s 5 -i shot.dng -o out.avif \f[R] .fi .SS steam-dl .IP .nf \f[C] Synopsis: steam-dl Launches Steam under systemd-inhibit, preventing the system from going idle or sleeping while a download is in progress. \f[R] .fi .SS spark .IP .nf \f[C] Synopsis: spark [--min=] [--max=] [numbers...] Renders a Unicode sparkline bar chart for a sequence of numbers. Reads from stdin if no numbers are given. spark 1 1 2 5 14 42 echo \[dq]3 7 2 9 1\[dq] | spark \f[R] .fi .SS yt-dlp .IP .nf \f[C] Synopsis: yt-dlp [args...] URL [URL...] Wraps yt-dlp, prepending sane defaults: --sponsorblock-remove all, --embed-subs, --embed-metadata, and --embed-thumbnail. Each default is suppressed when you already pass that flag, its alias, or its negation (e.g. --no-embed-thumbnail drops the thumbnail default; --no-sponsorblock or your own --sponsorblock-remove drops ours). All other arguments pass through unchanged, and --help falls through to real yt-dlp. Opinionated component (C1 aliases); when disabled it passes straight through to the system yt-dlp. yt-dlp dQw4w9WgXcQ yt-dlp --no-embed-thumbnail dQw4w9WgXcQ \f[R] .fi .PP * * * * * .SS 5.14 Miscellaneous .SS config-help .IP .nf \f[C] Synopsis: config-help [SECTION] config-help [SECTION] --html config-help [SECTION] --man config-help -h | --help Opens the offline fish shell configuration manual. Without flags, opens the Markdown source in the best available pager (ov > bat > man > less > cat). If SECTION is given, jumps to the first heading matching that keyword (case-insensitive; checks fish-config.index aliases first). Flags: --html / -w Open docs/html/index.html in the default browser. If SECTION is given, opens at the matching anchor. Detects the browser via xdg-mime x-scheme-handler/https, then known binaries, then xdg-open as last resort. Respects $fish_help_browser and $BROWSER. --man / -m Open docs/fish-config.1 via man -l directly. If SECTION is given, jumps to the nearest match. --help / -h Print usage and navigation key reference. config-help keybindings config-help pkg config-help --html config-help pkg --html config-help --man config-help pkg --man Also available as: help config [SECTION] [FLAGS] \f[R] .fi .SS open-url .IP .nf \f[C] Synopsis: open-url [-s|--silent] [-v|--verbose] open-url -h | --help Opens a URL or file:// URI in the best available graphical web browser, backgrounded so it never blocks the terminal. Resolves a real browser binary rather than deferring to xdg-open, whose MIME dispatch can hand local text/html files to non-browser apps (e.g. ebook readers). Silent by default: prints nothing on success (errors always go to stderr). Pass --verbose / -v to report which browser is launched; --silent / -s is accepted for explicitness. Resolution order: 1. $fish_help_browser (explicit override) 2. $BROWSER (validated; errors if not a command) 3. xdg-mime default handler for x-scheme-handler/https 4. First known browser binary found in a built-in list 5. xdg-open (last resort) open-url https://git.rootiest.dev/rootiest/fish-config open-url \[dq]file://$HOME/.config/fish/docs/html/index.html\[dq] Used internally by config-help --html. Typo abbreviation: url-open (expands to open-url on space/enter). \f[R] .fi .SS repo-open .IP .nf \f[C] Synopsis: repo-open [-p|--print] [-r|--root] repo-open -h | --help Opens the web page for the current repository\[aq]s \[ga]origin\[ga] remote in a browser (via open-url). Deep-links to the current branch when it exists on the remote \[em] falling back to the remote\[aq]s default branch (main/master) otherwise \[em] and to the current sub-directory when run below the repo root. The remote URL is normalized from HTTPS and SSH/scp forms (git\[at]host:owner/repo.git, ssh://\&..., https://\&...). The web path layout is provider-specific; the provider is resolved in order: 1. git config browse.provider (per-repo or --global override) 2. Hostname heuristic (github / gitlab / gitea / bitbucket; codeberg → gitea) 3. Default: github-style layout Self-hosted hosts the heuristic can\[aq]t classify (a Gitea/GitLab instance on a custom domain) need a one-time override: git config browse.provider gitea Flags: --print / -p Print the resolved URL instead of opening it. --root / -r Ignore the current sub-directory; link to the repo root. --help / -h Show usage. repo-open repo-open --print repo-open --root Typo abbreviation: open-repo (expands to repo-open on space/enter). \f[R] .fi .SS config-update .IP .nf \f[C] Synopsis: config-update [-h] [-n] [-f] Pulls the latest fish configuration from the upstream repository (https://git.rootiest.dev/rootiest/fish-config.git) into \[ti]/.config/fish. The remote URL is hard-coded, so this works on fresh clones with no git remote configured. All git output is suppressed; colored messages report fetch and merge status. After a successful pull, run \[ga]exec fish\[ga] to reload. Flags: --dry-run / -n Fetch and show available commits without applying them. --force / -f Stash local changes, pull, then restore the stash. --help / -h Show usage. config-update config-update --dry-run config-update --force \f[R] .fi .SS config-settings .IP .nf \f[C] Synopsis: config-settings [-h] Opens an interactive TUI for managing fish configuration settings across four pages, without having to type or remember variable names. Tab cycles forward through the pages; Shift-Tab cycles backward. Universal \[em] opinionated category toggles (C1\[en]C6) + master, persistent (set -U) Session \[em] the same toggles, current shell only (set -g) Sponge \[em] sponge history-scrubbing settings: delay, successful exit codes, purge-only-on-exit, allow-previously-successful, and extra sensitive variable-name tokens Paths \[em] scrollback log directory, scrollback max files, the user-dots path, and the user-dots convenience symlink toggle (Dots link) Toggle rows use ← → (or h/l) along an OFF ← DEFAULT → ON scale; DEFAULT erases the variable so the master switch / built-in default applies. Value rows (the path/int/list settings on the Sponge and Paths pages) use Enter to edit inline; ← / h clears the value back to its default. List rows (e.g. Extra secret, OK codes) accept values separated by commas and/or whitespace \[em] \[dq]A, B\[dq], \[dq]A,B\[dq] and \[dq]A B\[dq] all yield the same two entries. Changes apply immediately. Always available regardless of the __fish_config_opinionated master state. The Sponge and Paths pages always write universal variables \[em] these are persistent, set-and-forget settings with no per-session scope. Editing a scrollback row updates both the __fish_scrollback_history_* source-of-truth variables and the exported SCROLLBACK_HISTORY_* mirrors, so the AUR/tmux/ zellij log wrappers (which read the exported names) see the change in the running session. The panel adapts to the terminal width automatically, selecting from four layout tiers (with a 6-column buffer on each side before stepping up to the next tier) and horizontally centering the box. The panel redraws within \[ti]0.3 s of a terminal resize with no keypress required. COLUMNS >= 90 → 78-wide panel (most detail) COLUMNS >= 86 → 74-wide panel COLUMNS >= 82 → 70-wide panel COLUMNS < 82 → 52-wide panel (default) Navigation: ↑ ↓ / k j Move cursor ← → / h l Toggle rows: OFF ← DEFAULT → ON ← / h Value rows: clear to default Enter Value rows: edit inline (Sponge / Paths pages) Tab / S-Tab Next / previous page q / Escape Exit Flags: --help / -h Show usage. config-settings \f[R] .fi .SS config-toggle (deprecated) .IP .nf \f[C] Deprecated alias for config-settings. Prints a deprecation notice to stderr, then delegates all arguments to config-settings. config-toggle \f[R] .fi .SS bash .IP .nf \f[C] Synopsis: bash [args...] Switches to bash, with XDG config applied. On exit, $SHELL is reset back to fish. \f[R] .fi .SS bd-pull .IP .nf \f[C] Synopsis: bd-pull Fetches unlinked Gitea issues and creates local Beads entries, updating issue titles with the assigned Beads IDs. Requires $GITEA_TOKEN and $GITEA_URL to be set. bd-pull rootiest/fish-config \f[R] .fi .SS cheat .IP .nf \f[C] Synopsis: cheat [args...] Displays a colorized cheatsheet using cheat -c, falls back to tldr, then man. cheat tar cheat git \f[R] .fi .SS cffetch / ffetch .IP .nf \f[C] Synopsis: cffetch [args...] / ffetch [args...] Clears the screen and displays system information via fastfetch with the custom config at \[ti]/.fastfetch.jsonc. Falls back to neofetch. \f[R] .fi .SS dockup .IP .nf \f[C] Synopsis: dockup [-h] [directory] Pulls latest Docker images, restarts services in the given Docker Compose project, and prunes dangling images. dockup \[ti]/myapp \f[R] .fi .SS joplin .IP .nf \f[C] Synopsis: joplin [args...] Runs the Joplin CLI with Node.js deprecation warnings suppressed. joplin ls \f[R] .fi .SS ld .IP .nf \f[C] Synopsis: ld Launches lazydocker targeting the currently active Docker context, detected via docker context inspect. \f[R] .fi .SS replay .IP .nf \f[C] Synopsis: replay Runs Bash commands and replays any resulting changes to environment variables, aliases, and the working directory back into the current Fish session. Useful for sourcing Bash scripts. replay \[dq]source \[ti]/.bashrc\[dq] replay \[dq]export FOO=bar\[dq] \f[R] .fi .SS kitty-logging .IP .nf \f[C] Synopsis: kitty-logging [install|uninstall|status|dismiss] [-h] Manages the Kitty scrollback watcher that powers C5 logging. Ships a canonical, version-marked watcher and installs it into the Kitty config directory, wiring it into kitty.conf through a sentinel-marked managed block. Commenting out any conflicting watcher line avoids double-capture. Commands: install Copy/refresh the watcher and add the managed block uninstall Remove the managed block and the watcher file status Show wiring, installed watcher version, and C5 state dismiss Stop the per-session setup reminder Runtime capture stays governed by the C5 .logging_disabled sentinel, so disabling __fish_config_op_logging makes the watcher inert without uninstalling. Install affects new Kitty windows only. Example: kitty-logging install kitty-logging status \f[R] .fi .SS tmux-clean .IP .nf \f[C] Synopsis: tmux-clean Kills all detached (unattached) tmux sessions, leaving attached ones running. \f[R] .fi .SS wake-lock .IP .nf \f[C] Synopsis: wake-lock [args...] Runs a command under systemd-inhibit, preventing the system from going idle or sleeping until the command completes. wake-lock rsync -avz src/ dest/ \f[R] .fi .PP * * * * * .SH 6. DEPENDENCY CATALOG .PP fish-deps manages these tools. Run \f[V]fish-deps\f[R] to check status, or \f[V]fish-deps install\f[R] to install missing ones. .SS Required .IP .nf \f[C] fish Fish shell >= 4.0 fzf Fuzzy finder zoxide Smart cd with frecency \f[R] .fi .SS Integrations .IP .nf \f[C] wakatime Developer time tracking tailscale Mesh VPN client \f[R] .fi .SS Recommended .IP .nf \f[C] cargo Rust toolchain (via rustup); used by fish-deps to install Rust-based tools and to build fish from source. All paths are gated on type -q cargo and degrade gracefully. starship Cross-shell prompt; loaded via type -q starship guard. Without it the Catppuccin nim-style fallback prompt activates. uv Python package and project manager (Astral); used by the fish-from-source build path in fish-deps. All consumers degrade gracefully without it. direnv Per-directory environment loading; integration is fully guarded with type -q direnv. Without it the direnv hook is simply not loaded and auto-venv activates normally. paru AUR helper (Arch only; preferred); guarded throughout \[em] non-Arch systems silently skip AUR-specific paths. yay AUR helper (Arch only; fallback to paru); same guards apply. eza Modern ls replacement lsd ls replacement (fallback to eza) bat Syntax-highlighted cat btop Modern resource monitor dust Disk usage tree (Rust) duf Disk usage/free overview prettyping Colorized ping wrapper ov Modern pager (replaces less) ripgrep Fast line search lazygit Terminal git UI lazydocker Terminal docker UI trash Safe delete (trash-cli) kitty GPU-accelerated terminal (primary) wezterm GPU-accelerated terminal (alternative) python3 Standalone interpreter \[em] used by the paru/yay log cleaner. Note: uv does not provide python3 on PATH, and Arch\[aq]s base does not include it, so it is listed separately. All consumers degrade gracefully without it. yt-dlp Video/media downloader; backs the yt-dlp wrapper function. Optional \[em] the wrapper falls back to the system yt-dlp and the rest of the config works without it. \f[R] .fi .SS Install Methods .PP The install priority for each tool: .IP .nf \f[C] cargo Rust tools (eza, lsd, bat, dust, ov, ripgrep, trashy, zoxide, starship) \[em] always gets the latest crate version system PM paru / apt / brew / dnf / etc. \[em] for tools without a crate git clone fzf \[em] installed from GitHub to \[ti]/.fzf/ curl starship installer, fisher bootstrap, uv installer \f[R] .fi .PP * * * * * .SH 7. CUSTOMIZATION .SS Machine-local Configuration .PP Place machine-specific settings that should not be committed to git in: .IP .nf \f[C] $__fish_user_dots_path/local.fish \f[R] .fi .PP \f[V]__fish_user_dots_path\f[R] defaults to \f[V]\[ti]/.config/.user-dots/fish\f[R]. Set a custom location with: .IP .nf \f[C] set -U __fish_user_dots_path /path/to/your/dots/fish \f[R] .fi .PP Typical uses: additional PATH entries, local aliases, hostname-specific env vars, work-specific tool configs. .PP For convenience, a git-ignored \f[V]user-dots\f[R] symlink in the fish config directory tracks \f[V]$__fish_user_dots_path\f[R] so the overlay can be browsed from \f[V]\[ti]/.config/fish/\f[R]. It is created if missing and repointed if the path changes. Opt out by setting \f[V]__fish_user_dots_symlink\f[R] to a falsy value, or toggling \[lq]Dots link\[rq] off on the config-settings Paths page \[em] this stops generation and removes any existing link. It only ever manages a symlink and never clobbers a real file or directory at that path. .SS Secrets and API Keys .IP .nf \f[C] $__fish_user_dots_path/secrets.fish \f[R] .fi .PP Store API tokens, GPG keys, private credentials here. This file is never committed. It is sourced by local.fish directly, not by config.fish. .PP \f[V]local.fish\f[R] is sourced at the end of config.fish on every interactive session, so it and its companion secrets.fish can override anything set earlier. .SS Overriding Configuration Variables .PP Any variable set in local.fish after the main config loads takes effect. Example: to increase the scrollback history limit: .IP .nf \f[C] # in local.fish set -gx SCROLLBACK_HISTORY_MAX_FILES 200 \f[R] .fi .SS Fish Universal Variables .PP Some settings (fzf colors, theme) are stored in fish_variables via \f[V]set -U\f[R]. These are machine-local and git-ignored. Do not commit fish_variables. .SS Opinionated Components (Minimal Mode) .PP Every opinionated piece of this config is active by default but can be switched off through six category opt-out variables, each evaluated via __fish_variable_check. Set a variable to any falsy value (0, false, no, off, n) to disable its category; erase it or set a truthy value (1, true, yes, on, y) to re-enable. Unset means enabled. .PP An explicit per-category truthy value takes precedence over the master switch: setting __fish_config_opinionated=0 disables all unset categories, but a category with an explicit truthy value remains enabled regardless. .IP .nf \f[C] Variable Disables ------------------------------ ------------------------------------ __fish_config_op_aliases Command shadows and flag injection: ls->eza, cat->bat, cd->zoxide, rm->trash, less->ov, top->btop, ping->prettyping, ssh->kitten, du->duf/dust, mkdir/bash wrappers, history timestamps, grep/cp/mv/wget flag injection, help intercept, claude AGENTS.md auto-link __fish_config_op_autoexec Startup side-effects: Fisher bootstrap, theme apply, paru/yay wrapper generation, auto venv activation, WakaTime hook __fish_config_op_overrides Key and env overrides: Vi mode, exit->smart_exit, PAGER/MANPAGER, CDPATH, bang-bang system, autopair, puffer, starship prompt, theme colors, FZF_DEFAULT_OPTS, right prompt __fish_config_op_integrations Terminal/tool coupling: Kitty/ WezTerm window abbreviations, done notifications, spwin/tab/split, hist, logs, upgrade, WakaTime __fish_config_op_logging Logging & capture: scrollback capture on exit, paru/yay AUR log wrappers, Kitty watcher capture; sentinel file coordinates cross-process state __fish_config_op_greeting Greeting & first-run UI: per-session fish_greeting override (defines empty function late in config.fish to suppress distro greetings such as CachyOS fastfetch); first-run welcome banner in conf.d/first_run.fish \f[R] .fi .PP Examples: .IP .nf \f[C] # Disable command shadows only (rm becomes plain rm again): set -U __fish_config_op_aliases off # Full minimal mode \[em] disable all six categories at once: set -U __fish_config_opinionated 0 # Re-enable everything: set -Ue __fish_config_opinionated # Minimal mode but keep the greeting: set -U __fish_config_opinionated 0 set -U __fish_config_op_greeting 1 # (erase both to go back to full-flavor defaults) \f[R] .fi .PP For an interactive alternative to setting these variables by hand, run config-settings \[em] a full-screen TUI that flips any category (including C5 logging) on or off, per session or universally. See its entry in Section 5. .PP Notes: .IP \[bu] 2 Command shadows (rm, cat, ls, \&...) react immediately; conf.d-level components (bindings, prompt, abbreviations, hooks) take effect in new shells. .IP \[bu] 2 With aliases disabled, rm falls back to bare \f[V]command rm\f[R] \[em] files are deleted permanently, not trashed. .IP \[bu] 2 Disabled integration commands (spwin, tab, split, hist, logs, upgrade) print an error naming the variable that disabled them. .IP \[bu] 2 On CachyOS, the distro fish config\[cq]s own aliases, history override, and bang-bang bindings are stripped per category as well. .SS Component Reference .PP The following tables detail every component in each category. Use this reference to understand exactly which behaviors change when you toggle a category variable. .SS C1 \[em] Command Shadows .PP Disabling __fish_config_op_aliases restores standard system behavior for all of these commands. .IP .nf \f[C] Command / Alias Active behavior Disabled fallback ─────────────────────────────────────────────────────────────────────────── ls eza -l -a --icons --hyperlink system ls cat bat syntax-highlighted; dirs → ls /usr/bin/cat cd zoxide frecency-based navigation fish builtin cd rm moves files to trash (recoverable) command rm (permanent) less $PAGER → ov → less → more → cat system less du duf (disk overview) or dust (dir tree) system du top btop resource monitor system top ping prettyping --nolegend animation system ping ssh kitten ssh in Kitty terminal system ssh rg rg --hyperlink-format=kitty system rg mkdir verbose path-tree display on creation mkdir -p silently bash XDG bashrc + $SHELL reset on exit system bash history timestamps prepended to every entry fish builtin history cp / mv forced -i confirmation prompt cp / mv unmodified wget forced --continue (resume downloads) system wget grep/fgrep/egrep forced --color=auto system grep variants dir / vdir forced --color=auto system dir / vdir help config intercepts \[dq]help config\[dq] → config-help fish builtin help claude auto-links AGENTS.md as CLAUDE.md before launch command claude edit multi-editor launcher (GUI/term + fallbacks) $EDITOR/nvim/nano/vi \f[R] .fi .PP When C1 is disabled, \f[V]rm\f[R] uses bare \f[V]command rm\f[R] with no wrapper \[em] files are permanently deleted, not trashed. There is no intermediate safety net. .SS C2 \[em] Startup Side-Effects .PP These run automatically without any user action. Disabling __fish_config_op_autoexec prevents all of them. .IP .nf \f[C] Component Trigger What it does ─────────────────────────────────────────────────────────────────────────── Fisher bootstrap First shell only Downloads and installs fisher Fisher update After bootstrap Installs all fish_plugins entries Catppuccin Mocha theme First shell only Applies theme via fish_config paru wrapper Every startup Writes \[ti]/.local/bin/paru wrapper yay wrapper Every startup Writes \[ti]/.local/bin/yay wrapper Python venv activation On every cd Sources .venv/bin/activate.fish WakaTime command hook On every command Reports to WakaTime API Auto-pull fast-forward On entering a repo Background ff-only git pull user-dots symlink Every startup Links $__fish_config_dir/user-dots to $__fish_user_dots_path \f[R] .fi .PP When C2 is disabled: no Fisher install, no theme application, no paru/yay wrapper generation, no automatic venv activation, no WakaTime reporting, no auto-pull (the PWD handler is never registered), and the user-dots convenience symlink is not created. The symlink is git-ignored and only ever managed as a symlink \[em] a real file or directory at that path is left untouched. The symlink has its own opt-out independent of C2: set __fish_user_dots_symlink to a falsy value (or toggle \[lq]Dots link\[rq] off on the config-settings Paths page) to stop generating it and remove any existing link \[em] honoured even when C2 is enabled. Managed by the __fish_user_dots_link helper. The first-run completion marker (__fish_config_first_run_complete) is still set so the init does not re-run on subsequent shells. .PP Python venv activation fires on every directory change. If a directory uses direnv (.envrc present), direnv takes priority and auto-venv is skipped for that directory. .PP Auto-pull fast-forwards opted-in repositories in the background when you cd into them. The fish-config repo is always covered; other repos are added with the \f[V]auto-pull\f[R] command (see its entry in the functions reference). It only ever fast-forwards a clean repo whose branch has an upstream \[em] never rebases, merges, or overwrites work \[em] so it is a no-op on dirty trees, divergent branches, or repos without a remote. The handler fires once per repo entry (not on every sub-directory cd). The registry is machine-local at \f[V]$__fish_user_dots_path/auto-pull.list\f[R] (defaults to \f[V]\[ti]/.config/.user-dots/fish/auto-pull.list\f[R]) and is never committed. .SS C3 \[em] Key and Environment Overrides .PP These change fundamental shell behavior: how keys work, which pager opens, and what the prompt looks like. Disabling __fish_config_op_overrides removes all of them. .IP .nf \f[C] Override What it replaces or sets ─────────────────────────────────────────────────────────────────────────── Vi mode fish_vi_key_bindings replaces default Emacs mode exit → smart_exit exit wrapper that captures scrollback before closing PAGER=ov ov used by git, man, and all $PAGER-aware tools MANPAGER=bat pipeline man pages rendered with syntax highlighting CDPATH=. \[ti]/projects \[ti] bare dir names resolve against \[ti]/projects and \[ti] Bang-bang system ! and $ keys expand history; !\[ha], !*, !-N, !?str?, \[ha]old\[ha]new abbreviations; six expand_bang_* helpers Autopair ( [ { \[dq] \[aq] auto-close to (), [], {}, \[dq]\[dq], \[aq]\[aq] Puffer key intercepts . ! $ * keys intercepted for smart expansion Starship prompt fish_prompt replaced by Starship + OSC 133 markers Catppuccin colors 30+ fish_color_* variables set to Mocha palette FZF_DEFAULT_OPTS FZF themed to Catppuccin Mocha colors Right prompt fish_right_prompt: exit code (on failure) + dim timestamp; always rendered; Docker context added when starship+C3 active \f[R] .fi .PP The bang-bang system spans key_bindings.fish, abbr.fish, puffer.fish, and six expand_bang_*.fish functions. All are gated together \[em] disabling C3 removes the entire bang-expansion system at once. .PP When C3 is disabled, \f[V]exit\f[R] falls back to \f[V]builtin exit\f[R] with no scrollback capture, no Kitty IPC, and no file I/O on exit. The scrollback capture block is independently controlled by C5 (see below). .SS C4 \[em] Terminal and Tool Integration .PP These features couple the shell to specific external tools. Disabling __fish_config_op_integrations disables all of them. .IP .nf \f[C] Component Requires ─────────────────────────────────────────────────────────────────────────── \[ti]60 Kitty/WezTerm abbrs Active Kitty or WezTerm session (:w, :wv, :wh, :t, etc.) Done desktop notifications Graphical desktop with a notification daemon spwin Kitty or WezTerm tab Kitty, WezTerm, or Konsole split Kitty or WezTerm hist fzf + wl-copy (Wayland clipboard) logs fzf + ov; reads from \[ti]/.terminal_history/ upgrade paru or yay (Arch Linux only) WakaTime hook wakatime CLI and a configured API key \f[R] .fi .PP Disabled integration commands (spwin, tab, split, hist, logs, upgrade) print a colored error to stderr naming the variable that disabled them rather than silently failing. .SS C5 \[em] Logging and Capture .PP Five components capture shell output to disk. Disabling __fish_config_op_logging skips all capture and removes the logging wrappers. .IP .nf \f[C] Component What it captures ─────────────────────────────────────────────────────────────────────────── Scrollback capture Terminal session output saved to: \[ti]/.terminal_history/scrollback_YYYY-MM-DD_HH-MM-SS.log tmux pane capture Continuous pane stream via pipe-pane, saved to: \[ti]/.terminal_history/tmux_-w-p_YYYY-MM-DD_HH-MM-SS.log zellij pane capture Pane scrollback snapshot on shell exit, saved to: \[ti]/.terminal_history/zellij_-p_YYYY-MM-DD_HH-MM-SS.log paru wrapper All paru/AUR output captured to: \[ti]/.terminal_history/paru_YYYY-MM-DD_HH-MM-SS.log yay wrapper All yay/AUR output captured to: \[ti]/.terminal_history/yay_YYYY-MM-DD_HH-MM-SS.log Kitty watcher watcher.py captures scrollback when Kitty closes \f[R] .fi .PP The tmux capture starts automatically when fish launches inside any tmux pane ($TMUX is set). It uses tmux\[cq]s native pipe-pane to stream all pane output directly to disk without an intermediate process. Each fish shell session gets its own log file; a new log is created on each shell start (including exec fish and new splits). Before each new log, the oldest tmux_*.log files are pruned (by modification time) to keep the total within SCROLLBACK_HISTORY_MAX_FILES, matching the paru/yay wrapper behaviour. .PP The zellij capture works differently: Zellij has no live output-streaming facility like pipe-pane, so the log is taken as a one-shot snapshot when the shell exits, via \f[V]zellij action dump-screen --full --ansi\f[R] (the \[en]ansi flag preserves color). The dump is captured on the fish process\[cq]s stdout and written to the log file by fish itself (not via \f[V]--path\f[R], which would make the zellij server write the file). A fish_exit handler (registered whenever $ZELLIJ is set) writes the pane\[cq]s full scrollback and then prunes old zellij_*.log files the same way. Because the capture happens at exit, toggling __fish_config_op_logging takes effect on the next exit with no restart or sentinel coordination needed \[em] the C5 guard is re-checked when the handler fires. .PP LIMITATION \[em] zellij capture only fires on a clean shell exit (typing \f[V]exit\f[R], Ctrl-D, or a logout), because that is when the fish_exit handler runs. It does NOT capture when you close a pane or quit zellij through zellij itself: .IP \[bu] 2 Closing a pane signals the shell and tears the pane down concurrently, so even if the handler runs, \f[V]dump-screen\f[R] may find the pane buffer already gone. .IP \[bu] 2 Quitting zellij kills the zellij server, and \f[V]dump-screen\f[R] needs a live server to read from \[em] there is nothing left to snapshot. .PP This is a structural difference from tmux, NOT a bug. tmux streams pane output to disk continuously via pipe-pane, so whatever was printed is already saved no matter how the pane dies. Zellij can only snapshot, and the only reliable snapshot point from the shell is a clean exit. To guarantee a zellij pane is logged, end the session with \f[V]exit\f[R] or Ctrl-D rather than zellij\[cq]s close-pane or quit actions. .PP The Kitty watcher is managed by the kitty-logging command: it installs a version-marked watcher (fish-config-watcher.py) into the Kitty config directory and wires it into kitty.conf via a managed block. Inside Kitty, a non-blocking per-session reminder points first-time users at \f[V]kitty-logging install\f[R] until they install or run \f[V]kitty-logging dismiss\f[R]. Install affects new Kitty windows only; runtime disable is still handled by the .logging_disabled sentinel. .PP Logging coordination via sentinel file .PP C5 uses a sentinel file to synchronize state between the shell and out-of-process components (the Kitty watcher and all running shells): .IP .nf \f[C] \[ti]/.config/fish/.logging_disabled \f[R] .fi .PP Disabling __fish_config_op_logging: 1. Creates the sentinel immediately in every open shell. 2. Removes \[ti]/.local/bin/paru and \[ti]/.local/bin/yay logging wrappers; bare /usr/bin/paru and /usr/bin/yay are used instead. 3. Kitty\[cq]s watcher.py reads the sentinel on each save attempt and skips capture \[em] no Kitty restart required. 4. smart_exit stops saving scrollback logs. 5. Stops tmux pipe-pane capture in every open fish shell inside tmux. .PP Re-enabling __fish_config_op_logging: 1. Removes the sentinel in every open shell. 2. Regenerates paru/yay logging wrappers in \[ti]/.local/bin/. 3. Kitty watcher resumes capture on the next session exit. 4. Restarts tmux pipe-pane capture in every open fish shell inside tmux. .PP Changes propagate to all running shells through an event handler that fires whenever __fish_config_op_logging changes \[em] no shell restart needed. .PP Note: C3 and C5 compose independently. C3 controls whether the smart_exit wrapper is active at all; C5 controls only the scrollback-capture block inside it. With C3 disabled, exit is plain builtin exit regardless of C5. .SS C6 \[em] Greeting and First-Run UI .IP .nf \f[C] Component What it shows ─────────────────────────────────────────────────────────────────────────── First-run welcome banner One-time message on first interactive session fish_greeting override Empty function defined late in config.fish to suppress distro greetings (e.g. CachyOS sets fish_greeting to fastfetch by default) \f[R] .fi .PP When C6 is disabled, no greeting is printed by this config. Any greeting set by the distro or other configs runs normally \[em] this config simply does not override it. .SS Prompt and Theme .SS Starship .PP The primary prompt is Starship, initialized by conf.d/starship.fish. Configure it via \[ti]/.config/starship.toml. .PP conf.d/starship.fish defines a fish_prompt wrapper that only activates when starship is in PATH. It emits OSC 133;A (prompt start) immediately before Starship renders and OSC 133;B (input start) immediately after, placing both markers on the prompt line itself. This allows ov to use them as sticky section headers when browsing scrollback logs. Without Starship, fish\[cq]s built-in prompt handles these markers automatically. .SS Catppuccin Fallback Prompt .PP When Starship is absent or C3 overrides are disabled, a built-in nim-style two-line prompt activates from functions/fish_prompt.fish. No external dependencies \[em] fish builtins only. .PP Layout: .IP .nf \f[C] ┬─[user\[at]host:\[ti]/path] (main) ╰─>$ \f[R] .fi .PP Elements: .IP .nf \f[C] user Yellow (Catppuccin Yellow); red if root \[at]host Blue (local) or Teal (SSH) \[ti]/path prompt_pwd abbreviation (Catppuccin Text) (main) Current git branch in Catppuccin Pink; omitted outside repos ─[V:name] Active Python venv basename; omitted when none ─[N/I/R/V] Vi-mode indicator when vi bindings are active ┬─ / ╰─> Connector lines: Catppuccin Green on success, Red on failure \f[R] .fi .PP The right prompt (fish_right_prompt.fish) always renders, regardless of C3 state. On failure it shows a red ✘ and the exit code; on success it shows only the dim timestamp. When starship is installed and C3 is enabled, the active Docker context is also shown (if non-default): .IP .nf \f[C] ✘ 1 󰡨 myctx Fri Jun 12 00:51:21 2026 ← failed, starship+C3 active ✘ 1 Fri Jun 12 00:51:21 2026 ← failed, fallback prompt Fri Jun 12 00:51:21 2026 ← success (no ✘) \f[R] .fi .SS FZF .PP FZF is themed to Catppuccin Mocha via FZF_DEFAULT_OPTS set in integrations/fzf.fish. The colors applied: .IP .nf \f[C] Background: #1E1E2E (base) #313244 (surface0) Foreground: #CDD6F4 (text) Highlights: #F38BA8 (red) #CBA6F7 (mauve) #B4BEFE (lavender) \f[R] .fi .PP To customize, override FZF_DEFAULT_OPTS in local.fish. .SS Catppuccin Mocha Syntax Highlighting .PP The Catppuccin Mocha theme ships with this config in themes/ and is applied on first run via \f[V]conf.d/first_run.fish\f[R]. Colors are stored in fish_variables (universal). To switch variants, install a different theme from themes/: .IP .nf \f[C] fish_config theme save \[dq]Catppuccin Latte\[dq] \f[R] .fi .PP * * * * * .SH 8. FISHER PLUGINS .PP Fisher is bootstrapped automatically on the \f[B]first interactive session\f[R] via \f[V]conf.d/first_run.fish\f[R]. This also applies the Catppuccin Mocha theme and prints a one-time welcome message (gated by __fish_config_op_greeting; set it to 0 to suppress). Subsequent sessions skip all first-run logic with zero overhead. .PP To re-trigger first-run initialization (e.g., after a fresh install or for testing), run: .IP .nf \f[C] set -Ue __fish_config_first_run_complete \f[R] .fi .PP Then open a new shell. .SS Fisher-Managed Plugins .PP The following plugins are fully managed by Fisher. Their files are installed into the repo directory by Fisher and are listed in \f[V].gitignore\f[R] \[em] do not commit them. Fisher installs and updates them automatically. .IP .nf \f[C] jorgebucaran/fisher Plugin manager itself meaningful-ooo/sponge Remove failed commands from history \f[R] .fi .SS Sponge History Filtering .PP Sponge removes failed commands from history and, via conf.d/sponge_privacy.fish, also filters privacy-sensitive commands through three layers: .PP Layer 1 \[em] Static patterns (universal, persistent across sessions): Commands matching any of these structural signatures are never recorded: .IP .nf \f[C] --password / --token / --passphrase / --api-key flags with values Inline env assignments: GITHUB_TOKEN=xxx, MY_API_KEY=abc Fish set with sensitive names: set -gx GITHUB_TOKEN xxx URLs with embedded credentials: https://user:pass\[at]host HTTP Authorization headers: curl -H \[dq]Authorization: ...\[dq] Basic auth flags: curl -u user:pass sshpass, docker login -p, openssl -passin/-passout \f[R] .fi .PP Layer 2 \[em] Dynamic secret values (session globals, refreshed each login): On the first prompt, after secrets.fish has loaded, the literal values of all exported variables whose names suggest credentials (TOKEN, PASSWORD, SECRET, API_KEY, etc.) are collected, regex-escaped, and added as a session-scoped overlay. Because globals shadow universals in Fish, the combined list is what sponge sees. Rotating a token takes effect on the next login automatically. .PP Layer 3 \[em] Per-command filter (sponge_filter_secrets): Catches credentials in variables exported after login, such as tokens sourced from a project .env file mid-session. .PP To add your own persistent patterns: .IP .nf \f[C] set -U -a sponge_regex_patterns \[aq]your-regex-here\[aq] \f[R] .fi .PP To mark additional variable NAMES as credential-bearing (so Layer 2 scrubs their values), add name tokens \[em] via \f[V]config-settings\f[R] → Sponge, or directly: .IP .nf \f[C] set -U -a __fish_sponge_extra_sensitive ACME_API VAULT_PW \f[R] .fi .PP Tokens are folded into the Layer 2 name match case-insensitively as substrings, so ACME_API also covers ACME_API_KEY. (The match uses \f[V]--entire\f[R] to return the full variable name, so partial-name tokens dereference the right value.) .PP The \f[V]config-settings\f[R] Sponge page also surfaces sponge\[cq]s own tuning variables \[em] sponge_delay, sponge_successful_exit_codes, sponge_purge_only_on_exit, and sponge_allow_previously_successful \[em] so they can be changed without typing variable names. .SS Bundled Plugin Functionality .PP The remaining plugin functionality is bundled directly with this config rather than managed through Fisher. The bundled versions include customizations for Fish 4.x compatibility and improved behavior that differ from their upstream releases. Installing them through Fisher would overwrite these customizations. .PP Bundled components and their upstream origins: .IP .nf \f[C] catppuccin/fish → themes/ + conf.d/theme.fish PatrickF1/fzf.fish → functions/_fzf_*.fish + conf.d/fzf.fish franciscolourenco/done → conf.d/done.fish jorgebucaran/autopair.fish → functions/_autopair_*.fish + conf.d/autopair.fish nickeb96/puffer-fish → functions/_puffer_fish_*.fish + conf.d/puffer.fish \f[R] .fi .PP Do not run \f[V]fisher install\f[R] for these \[em] it will overwrite the customized versions. To update their behavior, edit the relevant bundled files directly. .SS fish_plugins Manifest .PP The \f[V]fish_plugins\f[R] file at the config root: .IP .nf \f[C] jorgebucaran/fisher Plugin manager itself meaningful-ooo/sponge Remove failed commands from history \f[R] .fi .PP To update all Fisher-managed plugins, run \f[V]fisher update\f[R] or \f[V]fish-deps update\f[R] which calls it as its first step. .PP * * * * * .SH 9. INSTALLATION .PP This configuration is managed as a git repository. To deploy on a new machine: .IP .nf \f[C] mv \[ti]/.config/fish \[ti]/.config/fish.bak # back up any existing config git clone https://git.rootiest.dev/rootiest/fish-config.git \[ti]/.config/fish \f[R] .fi .PP Then open a new Fish shell. Fisher installs automatically on first launch and the Catppuccin Mocha theme is applied. All other plugin functionality is bundled directly with this config and requires no additional installation. .SS Return Sentinel .PP config.fish ends with a return sentinel guard. Any lines appended after it by a tool\[cq]s setup command (starship init fish | source, zoxide init fish | source, etc.) will have no effect. All integrations are managed via conf.d/ files. .PP If a new tool\[cq]s shell integration appears to do nothing, check whether its setup command appended an init line below the sentinel and create a dedicated conf.d/.fish instead. .SS Updating .PP Pull the latest changes from the upstream repository without needing a configured git remote: .IP .nf \f[C] config-update Fetch and apply the latest commits from upstream config-update --dry-run Preview available changes without applying them config-update --force Stash local changes, pull, then restore the stash \f[R] .fi .PP The remote URL (https://git.rootiest.dev/rootiest/fish-config.git) is hard-coded, so this works on a fresh clone with no origin configured. All git output is suppressed. Run exec fish after a successful update to reload. .PP * * * * * .SH 10. PERSONALIZATION .PP Sensitive credentials and machine-specific settings are kept out of version control in a private directory. The path defaults to \f[V]\[ti]/.config/.user-dots/fish/\f[R] but can be overridden: .IP .nf \f[C] set -U __fish_user_dots_path /path/to/your/dots/fish \f[R] .fi .PP Or use the interactive TUI \[em] run \f[V]config-settings\f[R] and navigate to the \[lq]Dots Path\[rq] row (last row). Press Enter to type a new path, or ← / h to reset to the default. .PP config.fish sources local.fish from that directory on every interactive session. local.fish is responsible for sourcing its own secrets.fish: .IP .nf \f[C] $__fish_user_dots_path/ ├── secrets.fish API keys, tokens, passwords, personal identifiers └── local.fish Machine-specific paths, env vars, and sourcing secrets \f[R] .fi .PP fish_variables (auto-managed by fish) is excluded from this repo via \&.gitignore. Do not commit it. .SS secrets.fish .PP Store anything you would not commit to a public repo: API keys, auth tokens, passwords, and personal identifiers. .IP .nf \f[C] set -gx MY_NAME \[dq]Your Name\[dq] set -gx MY_EMAIL \[dq]you\[at]example.com\[dq] set -gx GPG_RECIPIENT \[dq]you\[at]example.com\[dq] set -gx GITHUB_TOKEN ghp_yourTokenHere set -gx OPENAI_API_KEY sk-proj-yourKeyHere set -gx GITEA_TOKEN yourGiteaTokenHere set -gx GITEA_CHOSEN_LOGIN your.gitea.instance set -gx KOPIA_PASSWORD yourKopiaPassword \f[R] .fi .SS local.fish .PP Store paths and variables specific to one machine \[em] things that would be wrong on any other system. .IP .nf \f[C] # CDPATH \[em] directories searched by cd set -gx CDPATH . /home/youruser/projects /home/youruser # Path to your shared .gitignore boilerplate set -gx GITIGNORE_BOILERPLATE \[ti]/.config/git/gitignore_boilerplate # SSH shortcuts abbr -a sshr \[aq]ssh you\[at]your-server.local\[aq] abbr -a sshw \[aq]ssh you\[at]work-server.example.com\[aq] # Docker context shortcuts abbr -a dcr \[aq]docker context use my-remote-server\[aq] abbr -a dcw \[aq]docker context use work-server\[aq] \f[R] .fi .PP local.fish is sourced at the end of config.fish with an existence check so the public config works cleanly on any machine without the private repo. local.fish in turn sources secrets.fish when it exists. .PP * * * * * .SH 11. VIEWING THIS MANUAL .SS With ov (recommended) .IP .nf \f[C] help config \f[R] .fi .PP ov renders the Markdown with syntax highlighting and section-based navigation. .IP .nf \f[C] Space next section \[ha] previous section Alt+u toggle section list sidebar / search forward n / N next / previous search match g go to line number j interactive jump target (line, %, or \[aq]section\[aq]) q quit \f[R] .fi .SS With bat .IP .nf \f[C] bat --language=markdown --paging=always \[ti]/.config/fish/docs/fish-config.md \f[R] .fi .SS As a man page .IP .nf \f[C] help config --man help config pkg --man \f[R] .fi .PP Opens the compiled docs/fish-config.1 directly via man -l, bypassing the pager fallback chain. If a section keyword is given, the pager opens at the nearest matching heading. The symlink is created once on first run (like an install step) and MANPATH is set each session, enabling the standard invocation: .IP .nf \f[C] man fish-config \f[R] .fi .PP NOTE: fish-config (hyphen) is this config\[cq]s man page. fish_config (underscore) is fish\[cq]s built-in browser-based configuration tool \[em] a completely separate command. Do not mix them up. .SS In the browser (HTML) .IP .nf \f[C] help config --html help config pkg --html \f[R] .fi .PP Opens docs/html/index.html in the default web browser. If a section keyword is given, the browser opens directly at the matching anchor (resolved via docs/html/sitemap.json). Browser detection queries the system\[cq]s x-scheme-handler/https MIME entry (via xdg-mime) to find the real browser binary, then falls back through known browser binaries (firefox, chromium, vivaldi, etc.), and finally xdg-open as a last resort. Set $fish_help_browser or $BROWSER to override. .SS As a wiki .PP The generated Markdown wiki lives in docs/wiki/. index.md provides the project overview and a full table of contents. Each section page has a navigation bar at the top linking to every other section. .PP The wiki is auto-generated from this file by the CI pipeline on every push to main that changes docs/fish-config.md. .SS Jumping to a section .IP .nf \f[C] help config keybindings help config abbreviations help config pkg help config logs help config fish-deps \f[R] .fi .PP The keyword is matched case-insensitively against section headings. .SH AUTHORS Rootiest.