This guide documents the shell architecture across Linux, macOS, and Windows in the NREDF dotfiles ecosystem, detailing feature parity, keybindings, aliases, functions, and configuration mechanics for Zsh, Bash, Fish, Nushell (nu), and PowerShell (pwsh).
None of the five is the default login shell — install and try any of them without disturbing your existing setup: fish or nu at a prompt starts an interactive session, and reload -s fish (or -s nu) hot-swaps the current one. Fish has no Windows build at all (Linux/macOS only); the other four run everywhere.
All five shells share a unified experience designed around modern developer ergonomics, with a small number of documented exceptions — see "Known Parity Exceptions" below.
| Capability | Zsh | Bash | Fish | Nushell | PowerShell (pwsh) |
|---|---|---|---|---|---|
| Prompt Engine | Oh-My-Posh (OneDark-Pro) |
Oh-My-Posh (OneDark-Pro) |
Oh-My-Posh (OneDark-Pro) |
Oh-My-Posh (OneDark-Pro) |
Oh-My-Posh (OneDark-Pro) |
| History Sync & Search | Atuin (Ctrl+r) | Atuin (Ctrl+r) | Atuin (Ctrl+r) | Atuin (Ctrl+r) | Atuin (Ctrl+r, UpArrow) |
| Fuzzy Finding | fzf (Ctrl+t, Alt+c) |
fzf (Ctrl+t, Alt+c) |
fzf (Ctrl+t, Alt+c) |
fzf (Ctrl+t, Alt+c, Ctrl+r) |
fzf (Ctrl+t, Alt+c) |
| Directory Navigation | zoxide hooked to cd, z, zi |
zoxide hooked to cd, z, zi |
zoxide hooked to cd, z, zi |
zoxide z, zi only — not hooked to cd (zoxide has no nushell cd integration upstream) |
zoxide hooked to cd, z, zi |
| Syntax Highlighting | fast-syntax-highlighting |
ble.sh (Bash Line Editor) |
Built in | Built in | PSReadLine |
| Inline Autosuggestions | zsh-autosuggestions |
ble.sh inline suggestions |
Built in | Built in | PSReadLine (HistoryAndPlugin) |
| Tab Completion Engine | Carapace (carapace-bin + fzf-tab) |
Carapace (bash-ble with descriptions) |
Carapace + fzf-powered Ctrl+Space widget |
Carapace native completion menu only — no fzf-powered widget (see exceptions) |
Carapace (native menu + fzf modal) |
| Auto-Pairing Quotes | zsh-autopair |
ble.sh auto-complete |
N/A (fish doesn't need it) | N/A (nu doesn't need it) | Custom PSReadLine chord (", ') |
| Plugin Manager | Sheldon | Git-cloned ble.sh |
None required | None required | None required (100% native CLI tooling) |
| Environment Sync | reload (supports -c, -d, -f, -p, -s) |
reload (supports -c, -d, -f, -p, -s) |
reload (supports -c, -d, -f, -p, -s) |
reload (supports -c, -d, -f, -p, -s) |
reload (supports -c, -d, -f, -p, -s) |
| Startup Profiling | reload -p / NREDF_PROFILE_STARTUP=1 |
reload -p / NREDF_PROFILE_STARTUP=1 |
reload -p / NREDF_PROFILE_STARTUP=1 |
reload -p / NREDF_PROFILE_STARTUP=1 |
reload -p / NREDF_PROFILE_STARTUP=1 |
SSH TOTP wrapper (nredf_ssh) |
nredf_ssh (shares bash's implementation via common/) — full ssh-getopt destination parsing (grouped flags, -p/-F attached or separate, --), -F honored, first-hop ProxyJump lookup |
nredf_ssh — see Zsh |
nredf_ssh — first-argument destination only (no getopt clustering or -F support yet) |
nredf-ssh — same simpler destination detection as Fish |
nredf_ssh — full ssh-getopt parsing + -F + ProxyJump (matches Bash/Zsh); falls back to plain ssh with a stderr note when sshpass isn't installed (the common case on Windows — no first-party build) |
Aqua GitHub-token wizard (nredf_aqua_token_setup) |
--set/--keyring/--env/--skip/--reset/--status + startup prompt, timed via read -t |
Same as Zsh (shares common/) |
Same flags; prompt timeout shells out to timeout/gtimeout if installed (see exceptions) |
Same flags; same timeout/gtimeout fallback as Fish |
Same flags; prompt timeout via [Console]::KeyAvailable polling — no external timeout binary needed |
| Remote multiplexer auto-attach (zellij) | Attaches over SSH/WSL per shell.yaml, skips inside zellij/VS Code/non-interactive (shares common/) |
Same as Zsh | Same behavior, own port | Same behavior, own port | Same behavior; reads WSL_DISTRO_NAME/WSL_INTEROP live instead of a chezmoi-baked NREDF_WSL (no chezmoi template in that part of pwsh's load chain — see Aliases.ps1.tmpl) |
| Local overrides | ~/.config/zsh/{aliases,rc,functions/} |
~/.config/bash/{aliases,rc,functions/} |
~/.config/fish/{aliases,rc} + fish's own native functions/ autoload |
~/.config/nushell/: two files only, env.local.nu, config.local.nu (see exceptions) |
~/.config/pwsh/{aliases.ps1,modules.ps1,functions/} |
- Dotfiles:
.zshenv.tmpl,.zprofile.tmpl,.zshrc.tmpl - Plugin Management: Managed by Sheldon via
~/.config/sheldon/plugins.toml- Loads Oh-My-Zsh core libraries (
completion.zsh,functions.zsh,history.zsh,misc.zsh,spectrum.zsh,termsupport.zsh,theme-and-appearance.zsh) - Curated plugins:
npm,rvm,extract,colored-man-pages,colorize,cp,git-extras,systemadmin,fzf-tab,fzf-zsh-completions,zsh-completions,zsh-autopair,calc,zsh-autosuggestions,fast-syntax-highlighting - Lazy Loading: Plugins are lazy-loaded on the first prompt display via
add-zsh-hook precmdto guarantee sub-millisecond shell startup.
- Loads Oh-My-Zsh core libraries (
- Completion Engine: Managed by Carapace (
carapace-bin) cached for 24 hours via_nredf_refresh_cached_shell_snippet, with custom declarative specs in~/.config/carapace/specs/.
- Dotfiles:
.bash_profile.tmpl,.bashrc.tmpl,.blerc.tmpl - Engine: Modern Bash 4.4+ / 5.x with ble.sh (Bash Line Editor)
- On macOS, automatically detects and invokes Homebrew Bash (
/opt/homebrew/bin/bashor/usr/local/bin/bash), bypassing Apple's legacy Bash 3.2. ble.shsources at the top of.bashrc(--attach=none) and attaches at the very end (ble-attach), providing syntax highlighting, fish-like autosuggestions, vim-mode support, and menu completion in standard Bash.
- On macOS, automatically detects and invokes Homebrew Bash (
- Completion Engine: Managed by Carapace (
carapace-bin) running after systembash_completionand cached for 24 hours via_nredf_refresh_cached_shell_snippet, with custom declarative specs in~/.config/carapace/specs/.
- Dotfiles:
home/dot_config/fish/config.fish.tmpl - Framework:
home/dot_local/share/nredf/shell/fish/—rc.tmplis a single, self-contained entry point (fish has no sibling shell to share a "common" rc with the way bash/zsh do), ported 1:1 from the bash function files since fish is dynamically scoped the same way bash is. - Completion Engine: Managed by Carapace (
carapace-bin) cached for 24 hours via_nredf_refresh_cached_shell_snippet, with the same declarative specs in~/.config/carapace/specs/. - Local overrides:
~/.config/fish/aliases,~/.config/fish/rc, plus fish's own native~/.config/fish/functions/*.fishautoload (nothing this framework implements).
- Dotfiles: thin stubs that just
sourceone canonical tree, deployed to every path nu might actually read —~/.config/nushell/{env,config}.nu(deployed on every OS, not just Linux) plus the OS-native fallback:~/Library/Application Support/nushell/{env,config}.nu(macOS) or~/AppData/Roaming/nushell/{env,config}.nu(Windows; Linux has no separate native path, XDG is its native path). Nu resolves its config directory from the real process environment before it reads any of its own files, and — confirmed live — prioritizes$XDG_CONFIG_HOME/nushellover its OS-native default the instantXDG_CONFIG_HOMEis set, on every OS, not only Linux. Since every other shell in this repo already exportsXDG_CONFIG_HOME, launching nu from (or with an environment inherited from) any of them makes nu read~/.config/nushelleven on macOS/Windows; launching nu with no such prior shell in the chain falls back to the OS-native path instead. Both locations get the same stub content so either path works. - Framework:
home/dot_local/share/nredf/shell/nushell/—env.nu.tmpl(env vars only, safe for non-interactivenu -l) andconfig.nu.tmpl(interactive-only setup), mirroring nu's own env.nu/config.nu convention instead of bash's single common rc. - Completion Engine: Managed by Carapace (
carapace-bin), which also stands in for the fzf-powered Ctrl+Space widget nu can't have (see "Known Parity Exceptions" below). - Local overrides: exactly two files,
env.local.nuandconfig.local.nu, seeded empty by chezmoi and never overwritten again — see "Known Parity Exceptions" below for why nu can't get bash's fuller cascade. - Environment model: nu's
defis not dynamically scoped — a function only mutates the caller's$envif declareddef --env, and every function in a chain that needs to reach top-level$envmust be--env, all the way up. Every state-mutating command in the nu port follows a "compute in a plaindef, assign in a thin--envwrapper" shape for this reason.
- Dotfiles:
- Entry points:
home/Documents/PowerShell/- Target for PowerShell 7+:
Documents\PowerShell\Microsoft.PowerShell_profile.ps1 - Target for Windows PowerShell 5.1:
Documents\WindowsPowerShell\Microsoft.PowerShell_profile.ps1(dot-sources PowerShell 7 profile) - Linux/macOS:
~/.config/powershellis symlinked directly to~/Documents/PowerShell
- Target for PowerShell 7+:
- Framework:
home/dot_local/share/nredf/shell/pwsh/- Deployed to
~/.local/share/nredf/shell/pwsh/on all platforms, matching the location of all other shells.
- Deployed to
- Entry points:
- Module Architecture:
Defaults.ps1: XDG paths, Aqua paths, Python paths, UTF-8 output encoding, default formatting.Modules.ps1: Zero external PowerShell modules required; hooks local overrides if configured.Aliases.ps1: Cross-platform command parity with Bash/Zsh.PSReadLine.ps1: Keybindings, prediction source (HistoryAndPlugin), nativefzfintegration, smart auto-pairing quotes.Functions/: one file per function (glob-bundled intoFunctions.bundle.ps1.tmpl, same mechanism as the other shells'functions/) —Functions.ps1itself holdsreload,sudo,md5,sha256;NREDF_DailySync.ps1,NREDF_Bw.ps1and the rest are their own files.Profile.ps1: High-performance startup orchestration with snippet caching (NREDF_RefreshCachedShellSnippet) for Oh-My-Posh, Atuin, Zoxide, and Carapace completions (including custom specs in~/.config/carapace/specs/).
- Specs:
home/dot_config/carapace/specs/holds one YAML spec per command carapace-bin doesn't know: the NREDF functions (reload,yy,nredf_ssh,nredf_aqua_token_setup,nredf-daily-sync) and CLI tools without a builtin completer (mise,kubectx,kubens,lsd,lazydocker,lazyjournal,zellij). - Aliases: bash can't complete an alias through its target, so every alias in
home/.chezmoidata/aliases.yamlwhose target needs it (k,kctx/ctx,kns/ns,lzg/lg,lzd,lzj/lj,ll/la/tree,pst) has its own thin spec that bridges to the target with$carapace.bridge.CarapaceBin([target]). A spec'saliases:field does not help here: it only names subcommand aliases and never registers a top-level command. - Cobra bridges:
home/dot_config/carapace/choices/makes carapace askflux,oras,stern,veleroandyqfor their own completions (the same filescarapace --choice flux/cobra@bridgewrites). - Cache lag: bash, zsh, fish and PowerShell only complete command names that were listed in carapace's init snippet, which is cached for 24 hours. A new spec or choice therefore appears only after
reload -c(or the next daily refresh); edits to an existing spec apply immediately. Nushell's snippet is a generic external completer, so it picks up new specs at once.
| Shortcut | Function | Description |
|---|---|---|
| Tab | Completion Menu | Interactive tab completion with descriptions via fzf-tab |
| Shift + Tab | Backward Cycle | Cycle backward through completion candidates in fzf-tab |
| Ctrl + Space | fzf Tab Completion | Open interactive fzf completion modal with descriptions |
| Ctrl + r | Atuin Search | Interactive fuzzy search across full command history |
| Ctrl + t | Fzf File Search | Fuzzy search files in CWD and insert selected path at cursor |
| Alt + c / Option+c | Fzf CD | Fuzzy search subdirectories and immediately cd into selection |
| → (Right Arrow) | Autosuggestion Accept | Accept full ghost-text autosuggestion |
| Ctrl + e | Autosuggestion / EOL | Accept autosuggestion or jump to end of line |
| Ctrl + a | Beginning of Line | Move cursor to beginning of command line |
| Ctrl + u | Backward Kill Line | Clear line before cursor |
| Ctrl + k | Forward Kill Line | Clear line after cursor |
| Ctrl + w | Backward Kill Word | Delete word before cursor |
| Ctrl + l | Clear Screen | Clear terminal screen |
Note
On macOS, Option+c produces ç or © by default. NREDF binds ç and © to fzf-cd-widget in Zsh so directory fuzzy jumping works without changing Terminal settings.
| Shortcut | Function | Description |
|---|---|---|
| Tab | Menu Completion | Open interactive ble.sh completion menu with Carapace descriptions |
| Shift + Tab | Backward Cycle | Cycle backward through completion candidates |
| Ctrl + Space | fzf Tab Completion | Open fzf fuzzy modal with completion candidates and descriptions |
| Ctrl + r | Atuin Search | Interactive fuzzy history search via __atuin_history |
| Ctrl + t | Fzf File Search | Fuzzy search files with live bat syntax preview |
| Alt + c / Option+c | Fzf CD | Fuzzy search directories with live lsd tree preview |
| → (Right Arrow) | ble.sh Complete | Accept highlighted completion candidate or inline autosuggestion |
| Ctrl + x Ctrl + e | Edit in $EDITOR | Open current command in Neovim/Vim, save to execute |
| Ctrl + c | Cancel / Interrupt | Abort current input or running process |
| Ctrl + l | Clear Screen | Clear terminal screen and redraw prompt |
| Shortcut | Function | Description |
|---|---|---|
| Tab | Fish Pager | Native completion menu with Carapace descriptions |
| Ctrl + Space | fzf Tab Completion | Open interactive fzf completion modal with descriptions (commandline-based, ported from bash's READLINE_LINE widget) |
| Ctrl + r | Atuin Search | Interactive fuzzy search across full command history |
| Ctrl + t | Fzf File Search | Fuzzy search files in CWD and insert selected path at cursor |
| Alt + c / Option+c | Fzf CD | Fuzzy search subdirectories and immediately cd into selection |
| Ctrl + l | Clear Screen | Clear terminal screen |
Note
On macOS, Option+c produces ç or © by default, same as zsh/bash — NREDF binds both to the fzf widget in fish too.
| Shortcut | Function | Description |
|---|---|---|
| Tab | Reedline Menu | Native completion menu fed by Carapace — nu's only completion-picking UI (see "Known Parity Exceptions" below) |
| Ctrl + r | Fzf History Search | fzf --nushell's Ctrl+R history widget |
| Ctrl + t | Fzf File Search | fzf --nushell's Ctrl+T file-insert widget |
| Alt + c | Fzf CD | fzf --nushell's Alt+C directory-jump widget |
| Ctrl + l | Clear Screen | Clear terminal screen |
Note
There is no Ctrl+Space fuzzy tab-completion widget in nu — Reedline (nu's line editor) has no primitive to replace the edit buffer with an external filter's output, which is what that widget depends on in every other shell here. See "Known Parity Exceptions" below.
| Shortcut | Function | Description |
|---|---|---|
| Tab | MenuComplete | Interactive terminal completion menu with Carapace descriptions |
| Shift + Tab | TabCompletePrevious | Cycle backward through completion candidates |
| Ctrl + Space | fzf Tab Completion | Open fzf fuzzy modal with completion candidates and descriptions |
| Ctrl + r / ↑ | Atuin History Search | Full-screen interactive history search powered by Atuin |
| Ctrl + t | fzf File Search | Fuzzy search files with bat syntax preview |
| Alt + c / Option+c | fzf CD | Fuzzy search directories with lsd tree preview and jump |
| Ctrl + d | ViExit | Exit session if buffer is empty |
| Alt + d | ShellKillWord | Delete next word forward |
| Alt + Backspace | ShellBackwardKillWord | Delete previous word backward |
| Alt + q | SaveInHistory | Stash current line in history and clear buffer for a quick command |
| " or ' | SmartInsertQuote | Automatically insert paired quotes and place cursor inside |
| → (Right Arrow) | Prediction Accept | Accept predictive IntelliSense suggestion from history/plugins |
NREDF guarantees that common development commands behave identically regardless of your current shell or operating system, across all five shells:
| Command | Target Tool | Description |
|---|---|---|
ls |
lsd |
Modern file listing with icons and colors — shadows Nushell's own structured ls builtin, see below |
ll |
lsd -lFh --git |
Long format listing with Git status flags and human-readable sizes |
la |
lsd -lAFh --git |
Detailed listing including hidden files and Git status |
tree |
lsd --tree |
Recursive tree view with icons |
cat |
bat --paging=never |
Syntax-highlighted output with OneDark-Pro theme, gated on bat |
vim / vi |
nvim |
Neovim editor, gated on nvim |
du |
dust |
Modern disk usage analyzer, gated on dust — not aliased in Nushell, see below |
df |
duf |
Modern disk free space viewer, gated on duf |
lzg / lg |
lazygit |
Terminal UI for Git |
lzd |
lazydocker |
Terminal UI for Docker and Docker Compose |
lzj / lj |
lazyjournal |
Terminal UI for multi-source log viewing & filtering |
k |
kubectl |
Kubernetes CLI shorthand |
kctx / ctx |
kubectx |
Fast Kubernetes context switcher |
kns / ns |
kubens |
Fast Kubernetes namespace switcher |
.. |
cd .. |
Go up one directory |
... |
cd ../.. |
Go up two directories |
.... |
cd ../../.. |
Go up three directories |
root |
sudo -E "HOME=$HOME" su -m |
Root shell that preserves your $HOME — gated on su, so not on Windows |
aptall |
apt update/full-upgrade/autoremove/autoclean |
One-shot Debian/Ubuntu system update — gated on apt, so only where it exists |
yy |
Custom Function | Open Yazi file manager; changes terminal working directory on exit |
cd <path> |
zoxide |
Smart jump (falls back to standard cd if path exists) — not in Nushell, see below |
z <query> |
zoxide query |
Jump directly to highest ranked directory matching query |
zi |
zoxide query -i |
Interactive fuzzy search directory selection |
Note
Nushell's cd is never replaced by zoxide (zoxide has no nushell-target cd integration upstream) — z/zi still work identically to every other shell here. Nushell's own ls/du/help are structured builtins (they return tables consumed in pipelines); ls is shadowed by the lsd alias here anyway, same as every other shell, but du deliberately is not — see "Known Parity Exceptions" below. help isn't aliased to tldr in any shell here (not just Nushell): it's a real, actively-used builtin/function in bash, fish and PowerShell too, not only nu's structured-table case, so aliasing it would shadow all three — run tldr <command> directly instead. cat/vim/vi/df are not nu builtins, so they get the same requires-gated behavior as every other shell (hand-written def --wrapped fallbacks in Nushell's case, since a requires-gated group can't be plain data-driven there — see .chezmoidata/aliases.yaml).
PowerShell also has its own which/touch fallback functions (filling a real Windows gap: neither binary exists there) and md5/sha1/sha256 convenience wrappers around Get-FileHash (Functions/Functions.ps1). These aren't in the table above because they're functions, not aliases to another tool, and Unix shells already have real touch/hashing tools natively — see "Known Parity Exceptions" below.
Real functions (not aliases to another binary), implemented once with identical names and behavior in bash/zsh, fish, Nushell and PowerShell. Each one checks its own tool dependency at call time and prints a clear message on stderr instead of failing silently if it's missing — none of them do any work at shell startup.
| Function | Requires | Does |
|---|---|---|
mkcd <dir> |
— | mkdir -p a directory, then cd into it |
extract <archive>... / x |
ouch |
Extract any archive format ouch recognizes (zip/tar/tar.gz/tar.zst/7z/rar/...) |
compress <out> <files...> |
ouch |
Compress files into an archive, format inferred from <out>'s extension |
fif <pattern> |
rg, fzf |
ripgrep for a pattern, fzf to pick a match (bat preview centered on the line), open $EDITOR there |
fe [query] |
fd, fzf |
fd for files, fzf (bat preview) to pick one, open in $EDITOR |
fbr |
git, fzf |
fzf-pick a local or remote branch, git switch to it |
flog |
git, fzf |
Browse git log --oneline --graph, previewing the selected commit with delta (falls back to plain git show) |
fkill [signal] |
fzf |
fzf-pick one or more processes (via procs, falling back to ps/Get-Process), kill them |
path |
— | Print $PATH, one entry per line |
ports |
— | List listening TCP ports (ss/lsof/netstat on Unix, Get-NetTCPConnection on Windows) |
nredf_bench_startup (nredf-bench-startup in Nu, NREDF_BenchStartup in PowerShell) |
hyperfine |
Benchmark interactive startup time of every installed shell |
Note
In zsh, oh-my-zsh's extract/x (sheldon, lazy-loaded on the first precmd) and its systemadmin plugin's path alias are defined after this file loads, so they win for interactive zsh sessions instead of the versions above — same output for path, but zsh's extract/x is OMZ's own implementation rather than the ouch-based one every other shell gets. Fixing this would mean editing sheldon's plugin list or its lazy-load hook, both existing files outside this change — see "Known Parity Exceptions" below. fif/fe/fbr/flog/fkill/mkcd/compress/ports/nredf_bench_startup are unaffected (OMZ defines none of them).
None of the following files are chezmoi-managed or committed to this repo — they live only on your machine, are yours to create, and chezmoi apply never touches or overwrites them. ~/.config/nredf/README.md is a shorter, on-disk version of this same section.
The same declarative format .chezmoidata/paths.yaml and .chezmoidata/aliases.yaml use internally. If this file exists, every shell reads and merges it in at chezmoi apply time (it is re-read on every apply, so editing it and re-applying picks up changes immediately). chezmoi deploys a copy-and-edit starting point at ~/.config/nredf/local.yaml.example — copy it to local.yaml in the same directory:
# ~/.config/nredf/local.yaml
nredf_paths_local:
- var: MY_TOOL_HOME # exported as $MY_TOOL_HOME if not already set
base: HOME # $HOME, or any other var already set by then (e.g. XDG_CONFIG_HOME)
parts: [".local", "my-tool"] # joined onto base with "/"
nredf_aliases_local:
- names: ["myalias", "ma"] # one or more names for the same command
command: "echo hello world" # a single target command; no pipes/flow controlBoth lists are optional and additive — they never replace the built-in entries. Two things this format deliberately can't express, by design:
- A
requires/existence gate on a local alias. Bash/zsh/fish/PowerShell would happily support one, but Nushell'salias/defcan't be conditionally defined inside anifblock (see below), so gating isn't offered here at all, to keep one file behaving the same on every shell. Everything innredf_aliases_localis defined unconditionally. - A pipeline, condition, or anything needing real control flow.
commandis a single command line, substituted as-is (bash/fish:alias; nu:alias; PowerShell:Set-Aliasor a one-line wrapper function).
For either of those, use the per-shell cascade below instead. A malformed local.yaml fails chezmoi apply loudly with a YAML parse error pointing at the bad line, rather than silently dropping your entries.
For anything local.yaml can't express — conditional aliases, real functions, arbitrary startup code — every shell loads its own files from its own ~/.config/<shell>/ directory, not from ~/.config/nredf/ at all. This is consistent across every shell including PowerShell (via XDG_CONFIG_HOME, set on Windows too — deliberately not $PROFILE's directory, which is Documents\PowerShell\ on Windows but ~/.config/powershell/ on Linux/macOS). There is deliberately no shared "all shells" or "bash+zsh" tier: a function's syntax is never portable across shells anyway, and local.yaml above already covers the one thing that genuinely was shareable (simple aliases/paths).
| Shell | Aliases | Startup code | Functions directory |
|---|---|---|---|
| Bash | ~/.config/bash/aliases |
~/.config/bash/rc |
~/.config/bash/functions/*.bash |
| Zsh | ~/.config/zsh/aliases |
~/.config/zsh/rc |
~/.config/zsh/functions/* |
| Fish | ~/.config/fish/aliases |
~/.config/fish/rc |
~/.config/fish/functions/*.fish — fish's own native autoload, nothing this framework implements |
| Nushell | not supported | ~/.config/nushell/env.local.nu, ~/.config/nushell/config.local.nu |
not supported |
| PowerShell | ~/.config/pwsh/aliases.ps1 |
~/.config/pwsh/modules.ps1 (module imports) |
~/.config/pwsh/functions/*.ps1 |
~/.config/<shell>/ is deliberately where each shell's local files live: it's already where you'd look for shell-specific config, and fish in particular already autoloads its functions/ directory as a native feature — putting a second, framework-specific mechanism anywhere else would only duplicate or collide with what the shell already does itself.
Every file in the table above except the functions directories is pre-seeded by chezmoi (create_: written once, empty except for a header comment and a commented-out example, never overwritten again) — there's nothing to create, just open and edit. Each functions/ directory instead has its own README.md with a matching example, since anything real dropped there gets sourced (or, for fish, autoloaded) on every shell startup.
aqua already supports a second, machine-local config file layered on top of the repo's aqua.yaml: if ~/.config/aquaproj-aqua/machine.yaml exists, every shell's startup appends it to AQUA_GLOBAL_CONFIG automatically (see nredf_aqua.bash/.fish/.nu/Defaults.ps1). Same packages: format as home/dot_config/aquaproj-aqua/aqua.yaml — add your own tools there without touching this repo.
mise natively loads config.local.toml alongside config.toml in the same directory (confirmed: mise config ls lists both). Add your own [tools] there; it's merged with home/dot_config/mise/config.toml.tmpl's pinned versions with no chezmoi involvement at all.
Each of the five shells provides a high-performance reload function with identical arguments (in Nushell, its typed named flags are generated from the same option set, so reload --help documents itself):
Usage: reload [options]
Options:
-c, --cache Delete 'Last Run Cache' and init script snippets
-d, --downloads Delete aqua pkgs (archives + binaries, keeps bin/ symlinks)
-f, --full Full refresh: clear caches + chezmoi / aqua / sheldon
-l, --last-run Delete only 'Last Run Cache'
-p, --profile Toggle startup profiling (or one-shot if combined with other options)
-s, --shell NAME Reload directly into a different shell (e.g. zsh, bash, fish, nu, pwsh)
-h, --help Show usage help
-l removes only the last-run stamps and keeps the cached init snippets, the sheldon cache and the zsh completion dump. -c and -f clear those as well; use one of them to pick up a tool upgrade immediately. Nushell's *.nu snippets are truncated rather than deleted, because nu's source needs each file to exist when config.nu is parsed.
-
Fast shell refresh:
reload
-
Measure shell startup latency:
reload -p
Prints step-by-step millisecond timings for Oh-My-Posh, Atuin, plugins, and custom functions.
-
Switch to Fish or Nushell from Bash/Zsh:
reload -s fish reload -s nu
-
Force clean rebuild of all CLI packages & cached scripts:
reload -f
Running standard yazi leaves the shell in whatever directory you started in. NREDF includes the yy function in all five shells:
yyWhen you navigate to a directory inside Yazi and quit with q, your shell automatically changes its working directory to the directory you were viewing in Yazi!
NREDF decouples all periodic maintenance and network-heavy upgrade tasks from interactive shell startup. Interactive shells start in milliseconds without waiting on network checks, git pulls, or package managers.
Daily maintenance is scheduled natively per operating system via chezmoi:
- macOS (
launchd):com.nredf.daily-sync.plist(managed viahome/private_Library/private_LaunchAgents/com.nredf.daily-sync.plist.tmpl). - Linux (
systemd --user):nredf-daily-sync.timer&nredf-daily-sync.servicein~/.config/systemd/user/. The timer isPersistent=true, so a run missed while the machine was off happens at the next boot. - Windows (Task Scheduler):
NREDF-DailySyncregistered withStartWhenAvailableto catch up after sleep.
The unified payload (nredf-daily-sync on POSIX, NREDF_DailySync on PowerShell) runs once daily in the background with low CPU and I/O priority:
- Package Upgrades: Homebrew (
brew update && brew upgrade && brew cleanup -son macOS). - Chezmoi Upgrade: Upgrades the chezmoi binary.
- Dotfiles Remote Sync: Fetches upstream dotfiles changes, fast-forwards Git, and runs
chezmoi apply --refresh-externals --force. A scheduled run has no terminal to unlock a password safe, so it first checks the one your secrets reference: Bitwarden must reportunlockedfrombw status(after restoringBW_SESSIONfrom the keychain, as shell startup does), 1Password must passop whoami, and a KeePassXC reference always needs its database password. If that check fails, the apply is skipped with a log line and the other steps still run. Runbwuand thenreload -fto catch up. PowerShell only pre-checks Bitwarden; for the other two it detects a locked safe from the failed apply's output. - Aqua Tools: Updates Aqua (
aqua update-aqua), ensures tool links (aqua install -a -l), and vacuums packages unused for >30 days (aqua vacuum -d 30). - Mise Tools: Installs missing or newly-pinned mise tools (
mise install --yes). - Zsh Plugins: Updates Sheldon plugin locks (
sheldon lock --update). Not on PowerShell. - tldr Pages: Refreshes the tldr page cache (
tldr --update). - oh-my-posh Session Caches: Deletes
*.omp.cachefiles older than 7 days from the oh-my-posh cache directory. Every shell gets a newPOSH_SESSION_ID, so these files otherwise pile up forever.
All runs are logged to ${XDG_STATE_HOME:-~/.local/state}/nredf/daily-sync.log (macOS/Linux) and $LOCALAPPDATA\nredf\daily-sync.log (Windows). reload -f (or nredf-daily-sync --verbose) also prints that output to the terminal.
If you have open terminals when the background sync completes:
- New & Upgraded Binaries: CLI tools in
/opt/homebrew/binor~/.local/share/aquaproj-aqua/binare immediately accessible in your existing shell. - Dotfiles, Aliases & Functions: Because running shells maintain their own in-memory environment, run
reloadto hot-reload the current session in place. - Manual Full Sync: To trigger a complete maintenance cycle and reload on demand, run
reload -f.
"Five-shell parity" (AGENTS.md) means every command, alias and completion is either implemented identically everywhere, or its gap here is deliberate, understood, and won't silently regress. These are the current gaps:
| Item | Affected shell(s) | Why | Resolution |
|---|---|---|---|
ls aliased to lsd |
Nushell | Every other shell here aliases ls to lsd, and nu gets the same alias for muscle-memory parity — but nu's own ls is a structured builtin returning a table, and the lsd-backed wrapper returns plain text instead, same as the external-ls-based shells. |
Accepted trade-off; scripts/pipelines inside nu that need structured output use ^ls (or another structured command) explicitly instead of the shadowed ls. |
du not aliased to dust |
Nushell | Unlike ls, nu's own du is a structured builtin actively used in pipelines (returns a directory-size table) — aliasing over it would break that, not just change formatting. |
Not implemented; bash/zsh/fish/PowerShell get du→dust, nu users run dust directly. |
help never aliased to tldr |
All five shells | Not just nu's case: bash's help builtin, fish's doc-browser help function, and PowerShell's Get-Help-wrapping help function are all real, actively-used commands, not dead weight to shadow. |
Not implemented anywhere; run tldr <command> directly instead of help <command>. |
which/touch fallback functions, md5/sha1/sha256 hash wrappers |
Only in PowerShell | which/touch fill a genuine Windows gap (neither binary exists there); md5/sha1/sha256 are convenience wrappers around Get-FileHash for verifying legacy vendor checksums. Unix shells already have real touch (and usually which) natively, and these are functions, not aliases to another CLI tool. |
Not ported; out of scope for the alias table (see the "New helper functions" carve-out — these are functions, tracked separately from alias parity). |
| Ctrl+Space fzf-tab completion widget | Nushell | Reedline (nu's line editor) has no primitive to replace the edit buffer with an external filter's output — every other shell's widget depends on exactly that. | Not implemented. Carapace's native Reedline completion menu (Tab) is nu's substitute. |
zoxide --cmd cd (replacing cd itself) |
Nushell | zoxide itself has no nushell cd integration — an upstream gap, not this repo's. |
z/zi aliases only; cd is never overridden in nu. |
| Same-session cached tool-init refresh (atuin/zoxide/mise/carapace/fzf) | Nushell | nu's source requires the target file to exist on disk before the file that sources it is even parsed — true even inside a runtime if path exists guard. A cache regenerated this session can only be sourced starting the next shell start. |
Chezmoi seeds an empty placeholder (create_/empty_) for each cache file so a cold source never fails outright; a stale-but-present cache is used for the rest of the current session and refreshes for the next one. |
| oh-my-posh's nu integration doesn't use the cached-snippet mechanism at all | Nushell | Unlike every other tool here, oh-my-posh init nu prints nothing (confirmed: empty stdout and stderr on success) — it writes directly into nu's own vendor-autoload directory (~/.local/share/nushell/vendor/autoload/, one of $nu.vendor-autoload-dirs), which nu sources automatically on its own next startup. |
config.nu just re-runs the generator on the same 24h throttle, with no cache file or source line of its own — the same one-restart lag applies, but because nu only rescans vendor-autoload at its own next startup, not because of the source restriction above. |
Fuller local-override files (aliases, rc, a local-functions directory) |
Nushell | Same source-needs-the-file-to-already-exist restriction rules out conditionally sourcing a maybe-missing file at all. |
Exactly two chezmoi-seeded files, env.local.nu and config.local.nu (seeded empty, never overwritten again) — one for env vars, one for interactive config, matching nu's own env.nu/config.nu split. |
| Directory-glob fallback when the function bundle is absent | Nushell | The fallback loop would itself need to source a runtime-determined file list — same restriction again. |
The generated bundle is nu's only load path, not a fast path with a fallback the way bash/zsh/fish have. |
Caller-name auto-detection for the throttle gate and mkdir-based lock (_nredf_last_run, _nredf_create_lock) |
Fish, Nushell | Neither has an equivalent of bash's FUNCNAME/zsh's funcstack. |
Both take an explicit key argument at every call site instead of inferring one. |
| Kitty terminal shell-integration | Nushell | Kitty ships integration scripts for bash/zsh/fish only — no nushell target exists upstream. | Not implemented; not something this repo can fix. |
dircolors/LS_COLORS integration |
Nushell | nu's own ls builtin has its own color theming ($env.config.color_config) and never reads LS_COLORS, unlike the external-ls-based ls/ll/la aliases every other shell here uses. |
Not implemented; low value for nu specifically, not a gap in the external-ls sense the other shells have. |
| Prompt-with-timeout for the aqua GitHub-token setup wizard | Fish, Nushell | Neither fish's read nor nu's input has a timeout flag at all (unlike bash's read -t). |
Shells out to timeout/gtimeout if one is installed; otherwise falls back to an untimed prompt, still gated on being a real interactive tty so it can never block a non-interactive shell. |
zcompile-equivalent bundle byte-caching |
Fish, Nushell | Neither has a bytecode-cache mechanism comparable to zsh's zcompile. |
Accepted as a minor, unavoidable cold-start cost; the cached-snippet mechanism still covers the genuinely expensive parts (tool inits). |
oh-my-posh tooltips (git details while typing git/lg/lzg/lazygit) |
Bash, Nushell | oh-my-posh only implements tooltips for zsh, fish and PowerShell; bash and nu's line editors have no hook for re-rendering the right prompt on each keystroke. | Not implemented. The tooltip only adds detail: branch and status stay in the main prompt in every shell, and the kube context stays on line two instead of becoming a tooltip for the same reason. |
PowerShell automatically restoring $env:SSH_AUTH_SOCK |
PowerShell, Nushell on native Windows | Pre-existing gap, unrelated to the fish/nu work above — flagged here so it isn't mistaken for a new one. On native Windows, nredf-set-ssh-agent returns immediately: its Unix-socket logic (id, chmod, ssh-agent -a) cannot run there, and a Unix SSH_AUTH_SOCK would override the OpenSSH named pipe. WSL is unaffected. |
Out of scope for this document; PowerShell users configure SSH agent forwarding another way for now. With SSH_AUTH_SOCK unset, Windows OpenSSH uses its \\.\pipe\openssh-ssh-agent pipe. |
NREDF uses mise as the polyglot runtime and tool manager across all platforms and shells. mise activate is automatically hooked and cached during shell startup, allowing directory-based tool switching (.tool-versions, mise.toml).
Error: File ... cannot be loaded because running scripts is disabled on this system.
Resolution: Run this command once in PowerShell:
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUserRun reload -p. The output will display exact timing metrics for each component (PowerShell shown; Bash/Zsh/Fish/Nu report their own equivalent steps):
[+ 2ms] NREDF_BwRestoreSession
[+ 4ms] oh-my-posh init
[+ 8ms] PowerShell modules
[+ 6ms] Atuin init
[+ 4ms] zoxide init
[+ 3ms] carapace completions
[+ 5ms] mise activate
[+ 3ms] inshellisense init
[+ 35ms] Total PowerShell profile startup time
Run reload -p a second time to turn off persistent profiling.