Requirements
+Dots is built for macOS and tested on Apple Silicon. Intel Macs are supported but not the primary target.
+| Requirement | +Details | +
|---|---|
| macOS | 12.0 (Monterey) or newer |
| Architecture | Apple Silicon preferred, Intel supported |
| Shell | Zsh (default since macOS 10.15) |
| Internet | Required for initial setup |
Installation
+Run this in your terminal to set up dots on a new machine:
+/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/CtrlUserKnown/dots/refs/heads/main/setup.sh)"Or clone and run manually:
+git clone https://github.com/CtrlUserKnown/dots ~/.dots
+~/.dots/setup.shWhat the setup script does
+-
+
- Checks your macOS version +
- Installs Homebrew and Gum if missing (with timeouts and fallbacks) +
- Prompts to install Ghostty, Neovim, optional tools, and dev packages +
- Installs required dependencies: eza, bat, fzf, fastfetch, zoxide +
- Creates all symlinks via
dots.py --repair-symlinks
+
Each package install has a 120-second timeout so a single hanging dep won't block everything else.
+Project structure
+Configs live in src/ organized by tool. The setup script symlinks them to the right locations.
| Path | +Contents | +
|---|---|
src/zsh/ | Zsh config, charModel theme, aliases, functions, dots.py, update-check |
src/ghostty/ | Ghostty config and custom themes |
src/bat/ | bat config and KnewPines color schemes |
src/fastfetch/ | System info display config with crab ASCII art |
src/herdr/ | herdr config with allow_nested = true |
src/opencode/ | opencode AI coding assistant config |
src/git/ | Git config |
dots command
+dots opens the curses TUI. It's the main interface for managing the dotfiles install.
dots # open the TUI
+dots -v # show version
+dots --health # run health check from the CLITUI menu items
+Menu items have numbered shortcuts (1 through 9). The available items depend on whether developer mode is active.
| View | +Description | +
|---|---|
| Health | Shows which tools are installed. Press Enter on a broken item to repair or install it in place. |
| Theme | Pick from 200+ built-in Ghostty themes. Changes apply immediately. |
| Settings | Toggle auto-updates, configure update frequency, trigger a manual update check. |
| Aliases | Browse all aliases with section headers. Press Enter to copy the alias value to clipboard. |
| Profile | Generate or import a personal config file with your settings, theme, and installed packages. |
| Edit Configs dev | Open config files in your editor directly. |
| Add Alias dev | Add a new alias interactively. |
| Git dev | Run git operations on the dotfiles repo. |
| View Logs dev | Browse update and install logs. |
| Reset dev | Re-run the full setup or reset specific parts. |
CLI flags
+dots --repair-symlinks # re-create all symlinks
+dots --install-deps # install required packages
+dots --install-optional # install optional packages
+dots --install-dev # install dev packages
+dots --set key=value # update a setting from the CLISettings via --set
+| Key | +Values | +
|---|---|
update_check | true / false |
update_frequency | Minutes (60, 1440, 10080, etc.) |
greeting | true / false |
theme | Any Ghostty theme name |
SSM
+SSM is a TUI SSH session manager. Sessions are stored in ~/.dots/src/herdr/session.json.
ssm # open the session managerKeybindings
+| Key | +Action | +
|---|---|
Enter | Connect to the selected session |
/ | Incremental search by name or host |
D | Duplicate the selected session (auto-names with -copy) |
y | Yank the session host to clipboard |
u | Update view: fetch and pull dotfiles from the remote host |
? | Full keybinding reference overlay |
q | Quit |
Aliases
+Aliases are defined in src/zsh/zsh/.aliases. Use dots Aliases view to browse them, or commands custom in the shell to see them parsed live.
| Alias | +Command | +Description | +
|---|---|---|
ls, la, ll, lla | eza | File listings with icons and colors |
cls | clear | Clear terminal |
reload | source ~/.zshrc | Reload Zsh config |
y | yazi | Terminal file manager |
f | fzf | Fuzzy finder |
b | btop | Resource monitor |
mux, attach | herdr | Terminal multiplexer |
opc | opencode | AI coding assistant |
llama | ollama | Local LLM runner |
dots | dots.py | Open the dots manager TUI |
Suffix aliases for .md, .rs, .swift, .py, .c, and .cr open files directly in $EDITOR.
Functions
+Shell functions are defined in src/zsh/zsh/.functions.
| Function | +Description | +
|---|---|
commands | Lists system commands via fzf with man page preview. commands custom shows aliases parsed live from .aliases. |
create <lang> <name> | Scaffolds new Swift, Java/Maven, Rust/Cargo, Crystal, or Git projects. |
duplicate | Safely clones files or folders with an optional rename. |
download <url> | Downloads URLs via curl or wget. |
ssm | Opens the SSH session manager TUI. |
Package tiers
+Dependencies are organized into three tiers. Required packages always install. Optional and dev packages are prompted during setup and can be installed later.
+| Tier | +When installed | +Examples | +
|---|---|---|
| Required | +Always | +eza, bat, fzf, fastfetch, zoxide | +
| Optional | +Prompted during setup | +nvim, herdr, btop, lazygit, yazi, carapace | +
| Dev | +Prompted during setup | +go, java, crystal, lua, docker, gh, cmake, gcc, ffmpeg | +
Neovim is optional. The editor fallback chain is nvim then vim then nano, so things work even if you skip it.
Install tiers manually
+python3 ~/.dots/src/zsh/zsh/dots.py --install-deps
+python3 ~/.dots/src/zsh/zsh/dots.py --install-optional
+python3 ~/.dots/src/zsh/zsh/dots.py --install-devSymlinks
+Symlinks are conditional based on what's installed. Tool-specific symlinks (Ghostty, herdr) are only created when the binary is present.
+| Target | +Source | +Condition | +
|---|---|---|
~/.config/zsh/ | src/zsh/zsh/ | Always |
~/.zshrc | src/zsh/.zshrc | Always |
~/.config/bat/ | src/bat/ | Always |
~/.config/fastfetch/ | src/fastfetch/ | Always |
~/.config/ghostty/ | src/ghostty/ | Ghostty installed |
~/.config/herdr/ | src/herdr/ | herdr installed |
Zsh config
+The Zsh config is split across two files to keep .zshrc stable even when switching branches in the dots repo.
| File | +Role | +
|---|---|
src/zsh/.zshrc |
+ Minimal bootstrapper (~15 lines). Sets DOTFILES_VERSION, checks the ~/.config/zsh symlink, then sources rc.zsh. |
+
src/zsh/zsh/rc.zsh |
+ All actual config: Homebrew, PATH, editor, plugins, completions, aliases, functions, theme, keybindings. This is where you make changes. | +
Plugins
+-
+
zsh-syntax-highlightingvia Homebrew
+ zsh-autosuggestionsvia Homebrew
+ zsh-history-substring-searchvia Homebrew
+ fzf-tabfrom GitHub, for fuzzy tab completions
+ carapacefor extended completions (optional)
+
Auto-LS hook
+Entering ~/.config or ~/development automatically lists directory contents.
Themes
+Ghostty
+Two custom themes ship with the repo. Use dots Theme to pick from any of the 200+ built-in Ghostty themes or apply a custom one.
| Theme | +Description | +
|---|---|
noir-cat | Dark theme based on Catppuccin Mocha with a neutral gray background instead of the purple-tinted default. |
knew-pines | Custom theme in the Rose Pine family. |
Zsh prompt
+The charModel prompt is minimal and fast. It shows an ∧ indicator when connected over SSH. Config lives at src/zsh/zsh/themes/charModel.
bat
+bat is configured to use the Rose Pine theme. KnewPines, KnewPines Moon, and KnewPines Dawn color scheme files are included at src/bat/themes/.
Auto-update
+An update-check.zsh script runs in the background on interactive shell start. Behavior is controlled by ~/.dots/.settings.
| Setting | +Default | +Description | +
|---|---|---|
update_check | true | Enable or disable background checks entirely |
update_frequency | 1440 (daily) | Minutes between checks. Supports 60 (hourly) to 10080 (weekly). |
When new commits are found upstream, you get a prompt to pull and re-symlink. Version comparison uses sort -V so semver bumps are detected correctly.
Manual update check
+-
+
- From dots TUI: Settings then "Check for updates" +
- From SSM TUI: press
uin the session list
+
Developer mode
+Developer mode unlocks advanced TUI items and changes update behavior to track commits instead of release tags.
+touch ~/.dots/.developer # enable
+rm ~/.dots/.developer # disableWhen active:
+-
+
- Update prompts show commit count and short SHA instead of version numbers +
- Skips version-stamp writes and upgrade notices on shell start +
- Unlocks: Edit Configs, Add Alias, Personal Pkgs, Git, View Logs, Reset in the TUI +
fzf
+fzf is integrated throughout the shell for file search, history, and completions.
+Default command
+fd --type f --hidden --follow --exclude .gitKeybindings
+| Binding | +Action | +
|---|---|
Ctrl-T | Insert file path into command line |
Alt-C | cd into selected directory |
Ctrl-R | Search shell history |
Alt-Enter | Open selected file in Neovim |
fzf-tab
+Replaces standard Zsh tab completion with fzf-powered fuzzy selection. < and > switch between completion groups. Previews are powered by bat (files) and eza (directories).
bat
+bat is configured as the primary file previewer for fzf. It's set to use Rose Pine theme and is available directly for viewing files with syntax highlighting.
bat somefile.py # view with highlighting
+bat --list-themes # see available themesThe BAT_THEME environment variable is managed in rc.zsh.
Testing
+A test suite in tests/ verifies the install process against an isolated home directory so nothing in your actual ~ is touched.
cd tests
+./test_setup.shGitHub Actions runs the test suite and ShellCheck linting on every push. Python syntax is also checked in CI.
+
+