fish-config/docs/fish-config.1

.\" 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
Scrollback history snapshots saved to \[ti]/.terminal_history on session
exit
.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
.PP
The configuration is split across:
.IP
.nf
\f[C]
config.fish          Main entry point; sets env vars and PATH
conf.d/              Auto-sourced fragments: keybindings, abbreviations,
                     theme, starship, zoxide, wakatime
functions/           One function per file, autoloaded by Fish
completions/         Tab completion scripts
integrations/        FZF Catppuccin theme and bindings
docs/                This offline documentation and compiled man page
\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
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.  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 \[ti]/.config/.user-dots/fish/local.fish.
.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      same as EDITOR
SUDO_EDITOR same as EDITOR
PAGER       ov (falls back to less)
\f[R]
.fi
.SS Scrollback History
.IP
.nf
\f[C]
SCROLLBACK_HISTORY_DIR        \[ti]/.terminal_history
SCROLLBACK_HISTORY_MAX_FILES  100
\f[R]
.fi
.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
   *   *   *   *   *
.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 (from fzf \[en]fish integration)
.IP
.nf
\f[C]
Ctrl+R          Search shell history with fzf
Ctrl+T          Insert a file path from fzf
Alt+C           cd into a directory chosen with fzf
\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          antigravity
ag.         antigravity .
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
.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 <source> <dest>
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] <dir>
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> [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
  <paths>     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 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 [args...]
Opens files in nvim. Falls back to $EDITOR, nano, vi.

edit \[ti]/.config/fish/config.fish
\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 branch
.IP
.nf
\f[C]
Synopsis:  branch <branch_name>
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> [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)
  6. pipx (Python tools)

When multiple methods are available you are prompted to choose.

Dependencies are grouped into three tiers:

  Required      uv, cargo, fish, fisher, starship, fzf, zoxide,
                direnv, paru/yay
  Integrations  wakatime, tailscale
  Recommended   eza, lsd, bat, btop, dust, duf, prettyping, ov,
                ripgrep, lazygit, lazydocker, trash, kitty, wezterm

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] <command> [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 <command> [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 <category>]
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 antigravity
.IP
.nf
\f[C]
Synopsis:  antigravity [args...]
Runs the agy CLI (Antigravity AI assistant) with noisy deprecation
warnings filtered from stderr.

antigravity chat
\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 antigravity-resume
.IP
.nf
\f[C]
Synopsis:  antigravity-resume
Resumes the most recent Antigravity session from the .antigravity_session
file in the current directory, or opens an interactive fzf picker if no
session file is found.
\f[R]
.fi
.SS claude-resume
.IP
.nf
\f[C]
Synopsis:  claude-resume
Resumes the most recent Claude Code session from the .claude_session
file in the current directory, or opens an interactive fzf picker.
\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 code-resume
.IP
.nf
\f[C]
Synopsis:  code-resume
Resumes the most recent AI session (Claude or Antigravity), preferring
the newest session file found in the current directory.
\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 <file>] [-o <file>] [-q <n>] [-s <n>] [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=<n>] [--max=<n>] [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
.PP
   *   *   *   *   *
.SS 5.14 Miscellaneous
.SS config-help
.IP
.nf
\f[C]
Synopsis:  config-help [SECTION]
           config-help --html
           config-help --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.
                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.
  --help / -h   Print usage and navigation key reference.

config-help keybindings
config-help pkg
config-help --html
config-help --man
\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 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 <owner/repo>
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 <topic> [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 <commands>
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 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 <command> [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
.SS zellij
.IP
.nf
\f[C]
Synopsis:  zellij [args...]
Launches zellij with the Catppuccin Mocha theme applied.
\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]
uv        Python package manager (Astral)
cargo     Rust toolchain (via rustup)
fish      Fish shell >= 4.0
fisher    Fish plugin manager
starship  Cross-shell prompt
fzf       Fuzzy finder
zoxide    Smart cd with frecency
direnv    Per-directory environment loading
paru      AUR helper (Arch only; preferred)
yay       AUR helper (Arch only; fallback)
\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]
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)
\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
pipx      Python-based tools
\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]
\[ti]/.config/.user-dots/fish/local.fish
\f[R]
.fi
.PP
Typical uses: additional PATH entries, local aliases, hostname-specific
env vars, work-specific tool configs.
.SS Secrets and API Keys
.IP
.nf
\f[C]
\[ti]/.config/.user-dots/fish/secrets.fish
\f[R]
.fi
.PP
Store API tokens, GPG keys, private credentials here.
This file is never committed.
.PP
Both files are sourced at the end of config.fish on every interactive
session, so they 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.
.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.
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.
.PP
The plugin list is maintained in fish_plugins at the config root.
.IP
.nf
\f[C]
jorgebucaran/fisher           Plugin manager itself
catppuccin/fish               Catppuccin Mocha color theme
PatrickF1/fzf.fish            fzf integration for Fish
franciscolourenco/done        Desktop notification when long commands finish
jorgebucaran/autopair.fish    Auto-pair brackets and quotes
meaningful-ooo/sponge         Remove failed commands from history
nickeb96/puffer-fish          !! / !$ / ./ expansion
\f[R]
.fi
.PP
Run \f[V]fisher update\f[R] to update all plugins, or
\f[V]fish-deps update\f[R] which calls fisher update as its first step.
.PP
   *   *   *   *   *
.SH 9. 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]
config-help --man
\f[R]
.fi
.PP
Opens the compiled docs/fish-config.1 directly via man -l, bypassing the
pager fallback chain.
The symlink and MANPATH are also configured automatically on shell start
for 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]
config-help --html
\f[R]
.fi
.PP
Opens docs/html/index.html in the default web browser.
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.