dotfiles

Personal shell environment, machine bootstrap, and cross-machine SSH trust for Neal's machines. One repo, cloned to ~/repos/dotfiles (or ~/Documents/repos/dotfiles) on every box, drives:

• a shared zsh config (aliases, functions, prompt, tool wiring) with a per-platform variant for Mac and Linux (Bazzite/Fedora, Ubuntu/Debian), built for parity — the same alias/function surface on both, branching only where the OS actually forces it
• one-shot bootstrap scripts that take a fresh machine to "fully set up", converging toward one generic script per OS (mac_bootstrap.sh, linux_bootstrap.sh) rather than per-machine scripts
• a single source of truth for known machines (machines.json) that generates both ~/.ssh/config and SSH-alias shell aliases
• passwordless SSH between machines, and the snippet to set it up
• a shared system health check (health.sh) with the same output shape on Mac and Linux
• Claude Code settings, rendered from a template so the one live secret (an MCP token) never touches the repo

Repo is public (github.com/nealrs/dotfiles) — see Data & secrets before adding anything to it.

Macs get the same shell/tool setup as everything else, but they aren't SSH targets — nobody dials into a laptop. machines.json is specifically the registry of SSH-reachable boxes (headless servers like gibson and kewtie), so Macs don't get an entry there and never appear in generated ~/.ssh/config Host blocks. A Mac still runs print_ssh_trust.sh/sshtrust so it can reach gibson/kewtie without a password — that direction is one-way.

Every machine still gets a ~/.hostname written during bootstrap (e.g. kewtie, gibson, or whatever you name a given Mac) — that's what selects its banner_<name> in ascii_art.sh at login. For SSH-target machines, that same name is also the key in machines.json.

git clone https://github.com/nealrs/dotfiles ~/repos/dotfiles
bash ~/repos/dotfiles/mac_bootstrap.sh

(or just run the script directly — it clones the repo itself if it isn't already at ~/repos/dotfiles.) Prompts for: email (SSH key comment), a machine name for ~/.hostname, git name/email if unset, and whether to generate SSH keys if missing. It checks for curl (ships with macOS — this is just a sanity check), then installs Homebrew + packages (git gh ruby nano uv eza bat fd ripgrep jq direnv zsh-autosuggestions zsh-syntax-highlighting fzf powerlevel10k 1password-cli), casks (Docker, 1Password, Slack, Ghostty, etc.), Mac App Store apps (Magnet, Tailscale), NVM + Node LTS + pnpm, symlinks the dotfiles (see File reference), generates ~/.ssh/config, and prints the SSH trust snippet.

Finish with: source ~/.zshrc, run p10k configure once (saves back into the repo), and run the ssh-copy-id commands it printed.

git clone https://github.com/nealrs/dotfiles ~/repos/dotfiles
bash ~/repos/dotfiles/linux_bootstrap.sh

One script, both distro families — it detects rpm-ostree vs apt-get and only branches where the package manager actually differs (1Password/Ghostty/Deskflow install method; apt-get needs no reboot, rpm-ostree does). Everything else is shared: host identity, a curl sanity check, Linuxbrew + packages (zsh starship atuin zoxide eza fzf jq direnv zsh-autosuggestions zsh-syntax-highlighting 1password-cli), sets zsh as the login shell, Flatpak apps (Slack, LocalSend) where flatpak is present, NVM + Node LTS + pnpm, SSH keys, symlinks, ~/.ssh/config, SSH trust snippet.

Finish with: log out/in (or exec $ZSH_PATH) to pick up zsh, source ~/.zshrc, run the ssh-copy-id commands it printed.

kewtie is the exception — it's a production, SSH-only home server with no console fallback, so linux_bootstrap.sh is never run on it unattended. See ubuntu.prd.md for why, and one-offs/kewtie_bootstrap.sh for the hand-walked, step-by-step equivalent (same end state, run and verified one section at a time, no chsh).

1. Bootstrap it (above) — this generates its own SSH keypair.
2. Add an entry for it to machines.json (name, user, local_ip if it has one, tailscale_hostname, tailscale_alias, ssh_set_env).
3. On every machine that should reach it (including Macs), run updatedots (pulls the repo, regenerates ~/.ssh/config) so it knows the new Host aliases, then sshtrust to get the ssh-copy-id command for the new target.

Just bootstrap it (above) and run sshtrust on it — no machines.json entry needed, since nothing will ever need to SSH into it. sshtrust already lists every current SSH target to authorize against.

Either way, this is still O(n) manual ssh-copy-id runs per new machine, not automatic — see print_ssh_trust.sh below if that ever becomes worth automating further.

Shared between .zshrc.mac and .zshrc.linux unless noted. Full source is the zshrc files — this is the map, not the last word.

General — ll/l/ls (eza), k (clear), ../..., reload/rel/resource (source ~/.zshrc), path (PATH one-per-line), json (pretty print via python3 -m json.tool), psg (ps aux | grep), o (open file manager here), npm → pnpm, pico → nano, repos (cd $REPOS), dots (cd $REPOS/dotfiles).

Tool swaps (only if installed) — cat→bat, find→fd, grep→rg.

Platform-specific

• Mac: dns (flush DNS cache), hosts (edit /etc/hosts), showfiles/hidefiles (Finder hidden files), copy/paste (pbcopy/pbpaste)
• Linux: copy/paste/pbcopy/pbpaste (wl-copy/wl-paste under Wayland, else xclip), open/o (xdg-open), hosts

Network/dev — ports (listening sockets — lsof on Mac, ss on Linux), headers (curl -I), web (quick HTTP server via python3), ii (connectivity + a title-tag fetch from neal.rs).

System — health (health.sh: CPU load/temp/fan, memory, disk free — same output shape on Mac and Linux, reading native OS commands directly rather than shelling out to another tool). h (cmds.sh: color-coded cheat sheet of every alias/function below — parses the section banners already in the active zshrc plus the SSH aliases machines.sh generates, so it can't drift from this list).

Docker/Podman — dockup/dockupbuild/dockdown/docklog/dockps/dockexec. On Linux, docker aliases to podman if Docker itself isn't installed; pc is podman compose when available.

Git — gs status, ga add -A, gc commit -m, gcl clone, gp/gpl push/pull, gb checkout -b, gco checkout, gl log graph, gd diff, gst/gsp stash/pop, gundo (soft-reset last commit).

Python (uv) — py (uv run python), pip→uv pip, uvr/uva/uvs/uvi/uvpy (run/add/sync/init/python).

SSH / machines — generated per host in machines.json by machines.sh: for each host with a local_ip, an alias named after it (e.g. kewtie → ssh kewtie-lan); for each host with a tailscale_alias, that alias (e.g. tsk → ssh kewtie-tailnet, tsg → ssh gibson-tailnet); plus any extra_aliases. tssh <name> connects to any host by name over Tailscale. genssh regenerates ~/.ssh/config from machines.json + ssh_config.base. sshtrust prints the ssh-copy-id commands to authorize this machine on every other one. ts/ts-status/ts-up/ts-down (Tailscale).

updatedots — git pull on the repo, genssh, re-renders ~/.claude/settings.json from the template and re-registers the neal-todos/jobbot/stonks-mcp MCP servers via claude mcp add (token step skips with a message if 1Password CLI isn't installed/signed in — see claude/claude_settings.sh), then re-sources ~/.zshrc.

Functions — wan/lan/net (public + local IPs, shown at login), weather (wttr.in), wifi (power-cycle Wi-Fi), mcd (mkdir + cd), rn (runs rename.sh — see below), mo (random line from motivation.md), hi (login banner: ASCII art for this host, net, mo, weather — this is what prints the WAN/LAN/weather block you see on every new shell). nvm stays lazy (only nvm.sh sourcing waits for the first nvm call) but the default Node version is primed onto PATH at shell startup, so node/npm work immediately without forcing the full load or fighting a system Node on PATH.

• Private SSH keys never live in this repo. Each machine generates its own keypair during bootstrap (ssh-keygen, prompted, skippable). Trust between machines is one-directional-per-pair and set up by copying a public key straight to the target's ~/.ssh/authorized_keys via ssh-copy-id (see print_ssh_trust.sh) — nothing key-related is ever committed.
• machines.json has hostnames, usernames, LAN IPs (RFC1918, only reachable from inside the home network), and Tailscale hostnames/aliases. None of this is a credential, but it's real topology about home infrastructure in a public repo — don't add anything more sensitive than that here (no tokens, no passwords, no public IPs of anything you don't want indexed).
• MCP server tokens (neal-todos, jobbot, stonks-mcp) are never stored in this repo. claude/claude_settings.sh reads each token from a 1Password reference (op://Private/to-do-mcp/token, op://Private/jobbot-mcp/token, op://Private/stonks-mcp/token) at bootstrap/updatedots time and registers the server via claude mcp add into ~/.claude.json, which is never written back into the repo. If op isn't installed or you're not signed in, it falls back to the previously-registered token, or a placeholder if there is none.
• .gitignore only excludes OS noise (.DS_Store) — nothing generated (rendered configs, keys, ~/.ssh/config) is ever written inside the repo in the first place, it's all written to $HOME or ~/.ssh/~/.config. Keep it that way: anything this repo writes should land outside the repo, not get committed.
• q11.json is an unrelated keyboard (QMK/VIA) config backup — not read by any script here, just parked in the repo for safekeeping.

Both zshrc files set REPOS="$HOME/repos", falling back to $HOME/Documents/repos if ~/repos doesn't exist. Bootstrap scripts always clone to ~/repos/dotfiles; the fallback exists for machines (like this one) where the repo instead lives under ~/Documents/repos/dotfiles.