This guide details setting up, using, and troubleshooting NREDF dotfiles on Linux (Debian/Ubuntu, Arch Linux, Fedora/RHEL, Linuxbrew, and WSL).
Using chezmoi directly:
sh -c "$(curl -fsLS get.chezmoi.io)" -- -b ~/.local/bin init --apply NemesisRE/dotfilesOr using the bootstrap script:
bash <(curl -fsSL https://raw.githubusercontent.com/NemesisRE/dotfiles/main/bootstrap.sh)Requirements:
curlandgit(automatically installed if missing on Debian/Ubuntu).
NREDF manages native prerequisite packages automatically via home/.chezmoidata/packages.yaml during chezmoi apply.
| Distribution | Package Manager | Core Prerequisites Managed |
|---|---|---|
| Debian / Ubuntu | apt |
git, curl, zsh, fonts-firacode, build-essential (C/C++ compiler for Tree-sitter), socat |
| Arch Linux | pacman |
git, curl, zsh, ttf-firacode-nerd, base-devel (C/C++ compiler for Tree-sitter), socat |
| Fedora / RHEL | dnf |
git, curl, zsh, fira-code-fonts, gcc, gcc-c++, make (for Tree-sitter), socat |
| Linuxbrew | brew |
Standalone Homebrew packages located at /home/linuxbrew/.linuxbrew |
All developer CLI tools (such as neovim, zellij, atuin, fzf, zoxide, lsd, bat, yazi, lazygit, lazydocker, lazyjournal, lnav, bottom, uv, ruff, ouch) are managed declaratively by aqua in ~/.config/aquaproj-aqua/aqua.yaml, keeping system package manager pollution to a minimum (Python is managed standalone via uv, and all archive compression/decompression via ouch).
- Default interactive shell for many setups.
- Uses Sheldon to manage plugins (
~/.config/sheldon/plugins.toml) with lazy loading. - Features Oh-My-Posh prompt (
OneDark-Pro), Atuin history sync, fzf completions, and fast-syntax-highlighting.
- Standard shell on almost all Linux distributions.
- Powered by ble.sh (Bash Line Editor) located at
~/.local/share/blesh/ble.sh. - Adds real-time syntax highlighting, fish-style autosuggestions, vim mode, and menu-completion directly to standard GNU Bash 4.4+.
- Install via Microsoft package repository or
snap install powershell --classic. - Symlinks
~/.config/powershellto~/Documents/PowerShell. - Uses modular configuration located at
~/.local/share/nredf/shell/pwsh/withPSFzf,Terminal-Icons,posh-git, andAtuin.
To switch active shells anytime without re-opening your terminal:
reload -s zsh # Switch to Zsh
reload -s bash # Switch to Bash
reload -s pwsh # Switch to PowerShellOn Linux desktop environments, Kitty is the recommended GPU-accelerated terminal emulator:
- Upstream Installation: Installed standalone to
~/.local/kitty.appwith binaries linked to~/.local/bin/, from a pinned GitHub release archive verified against a SHA-256 checksum before extraction — not the upstreaminstaller.shpiped intosh(version and hashes pinned in.chezmoidata/kitty.yamland kept current with Renovate). This avoids severely outdated distribution packages (like Debian/Ubuntuapt). - Desktop & Icon Integration: Chezmoi automatically creates and patches
kitty.desktopand icons in~/.local/share/applicationsand~/.local/share/icons. - WSL Excluded: Kitty installation is automatically skipped on WSL environments (where Windows Terminal on the host OS is used).
- Font:
FiraCode Nerd Font Mono, installed automatically from the pinned ryanoasis/nerd-fonts release archive (see.chezmoiexternals/fonts.toml.tmpland.chezmoidata/nerd-fonts.yaml), not a distro package. - Theme: Automatically imports the matching OneDark-Pro theme (
~/.config/kitty/current-theme.conf). - Scrollback: 10,000 lines with smart trailing space stripping.
- Copy on Select: Text selected with mouse is copied to system clipboard automatically (
copy_on_select clipboard).
NREDF includes pre-configured drop-down terminal settings in home/dot_config/kitty/quick-access-terminal.conf.tmpl and installs a Wayland-aware wrapper script: kitty-quake (aliased to kitty-quick-access).
-
Configuration Gate: You can choose your preferred Quake toggle key (
F12,Pause, ornone) duringchezmoi initor in~/.config/chezmoi/chezmoi.toml:[data.kitty] quake_key = "Pause" # Options: "F12" (default), "Pause", or "none"
-
KDE Plasma (Automatic): Chezmoi automatically configures the global shortcut in KDE Plasma using
kwriteconfigand restarts the shortcut daemon. -
Wayland Integration: Automatically exports
WAYLAND_DISPLAY="${WAYLAND_DISPLAY:-wayland-0}"so hotkey daemons and compositors can toggle the window reliably. -
Manual / Other Compositors:
- KDE Plasma (Manual): System Settings → Keyboard → Shortcuts, click Add New → Add Application..., select Kitty Quake Terminal, and set the shortcut.
- GNOME: Go to Settings → Keyboard → View and Customize Shortcuts → Custom Shortcuts. Add a shortcut with command
kitty-quake(or select Kitty Quake Terminal), e.g. bound to Pause or F12. - Sway: Add to your config:
bindsym Pause exec ~/.local/bin/kitty-quake - Hyprland: Add to
hyprland.conf:bind = , Pause, exec, ~/.local/bin/kitty-quake
- Ctrl + Shift + Enter: New window split
- Ctrl + Shift + t: New tab
- Ctrl + Shift + w: Close window
- Ctrl + Shift + Left / Right: Next / previous window
- Ctrl + Shift + Up / Down: Scroll line up / down
- Ctrl + Shift + PageUp / PageDown: Scroll page up / down
NREDF features an intelligent SSH Agent detection engine in nredf_set_ssh_agent.bash:
- Systemd User SSH Agent:
$XDG_RUNTIME_DIR/ssh-agent.socket - GNOME Keyring:
$XDG_RUNTIME_DIR/gcr/sshor$XDG_RUNTIME_DIR/keyring/ssh - Bitwarden Desktop:
~/.bitwarden-ssh-agent.sock(or Snap/Flatpak container sockets) - 1Password:
~/.1password/agent.sockor~/.config/1Password/agent.sock - GnuPG Agent: Uses
gpgconf --list-dirs agent-ssh-socketwhen GPG agent mode is configured.
Agent sockets are probed with a 2 second timeout (timeout/gtimeout, when installed), so a locked desktop agent cannot stall shell startup. If no agent is found, NREDF starts its own ssh-agent on ~/.ssh/auth_sock; a lock directory makes shells that start at the same time share one agent instead of racing.
In WSL 1/2, NREDF can bridge your Windows SSH Agent (e.g. Bitwarden Desktop or Windows OpenSSH Service) into WSL automatically:
-
Uses
socatandnpiperelay.exeto bridge//./pipe/openssh-ssh-agentto~/.ssh/auth_sock. -
To enable:
# On Windows host: winget install albertony.npiperelayIn WSL, NREDF automatically detects
npiperelay.exeand establishes the relay socket. -
Opening links in your Windows browser: on WSL,
BROWSERis set for you, whichgh,git web--browseand anything else that honours it will use. It iswslview(from wslu) when that is installed, because it quotes URLs so&survives and converts Linux paths; otherwise it falls back tocmd.exe /c start. On Ubuntu,sudo apt install wslu. ABROWSERyou set in~/.config/bash/rcor~/.config/zsh/rctakes precedence.- wslview 4.1 probes a URL with
curlfirst and treats it as a file path if that fails, so a link to a host that is not reachable yet can misbehave. If you hit that, addexport WSLVIEW_SKIP_VALIDATION_CHECK=0to the same file.
- wslview 4.1 probes a URL with
-
Terminal Multiplexer (Zellij): Automatic Zellij startup is disabled by default on WSL so terminal tabs open directly into your shell. To have Zellij auto-attach on WSL:
- Run
chezmoi init --prompt && chezmoi applyand answeryesto the WSL multiplexer prompt (or setwsl_multiplexer = truein~/.config/chezmoi/chezmoi.tomlunder[data.shell]). - Alternatively, set
export NREDF_SHELL_WSL_MULTIPLEXER=truein~/.config/bash/rcor~/.config/zsh/rc.
- Run
On Debian/Ubuntu systems, use the built-in alias:
aptall
# Runs: sudo apt update && sudo apt full-upgrade -y && sudo apt autoremove --purge -y && sudo apt autocleanSwitch to root while preserving your user environment variables:
root
# Runs: sudo -E "HOME=${HOME}" su -myy
# Opens Yazi. Navigating to a folder and exiting with 'q' changes your terminal directory!On Linux systems running systemd, NREDF installs a user-level timer and service:
- Service:
~/.config/systemd/user/nredf-daily-sync.service(runsnredf-daily-syncwithNice=10andIOSchedulingClass=idle). - Timer:
~/.config/systemd/user/nredf-daily-sync.timer(triggers daily at 7:00 AM withPersistent=trueto run upon wake/boot if off). - Tasks: Upgrades
chezmoi, syncs dotfiles, updatesaquatools, vacuums old tool versions, and updates Sheldon plugin locks. - Logs:
${XDG_STATE_HOME:-~/.local/state}/nredf/daily-sync.log.
Check timer status anytime:
systemctl --user list-timers nredf-daily-sync.timerCause: The current environment has an ungenerated or invalid UTF-8 locale set.
Resolution:
NREDF automatically checks available locales via locale -a and defaults to en_US.UTF-8 or C.UTF-8. To generate standard locales on Debian/Ubuntu:
sudo locale-gen en_US.UTF-8
sudo update-locale LANG=en_US.UTF-8Cause: Missing terminal OSC 52 passthrough or missing clipboard binary on headless Linux. Resolution:
-
NREDF configures Neovim, Zellij, and Kitty with OSC 52 clipboard passthrough, which copies text to your desktop clipboard directly across SSH.
-
On desktop Linux, ensure
wl-clipboard(Wayland) orxclip/xsel(X11) is installed:sudo apt install wl-clipboard xclip # Debian/Ubuntu sudo pacman -S wl-clipboard xclip # Arch
If aqua install warns about GitHub API limits:
aqua token setFollow the prompt to enter a personal GitHub token (no permissions needed for public repos).