equisdots · dots

Meta installer and updater for the equisdots desktop stack. One command clones every repo of the org, places each piece where it belongs and keeps them in sync.

Stack

Repo	What it provides	Installed to
hyprland	Compositor config (Lua), scripts, installer	~/.config/hypr
shell	Quickshell UI (bar, panels, editor, popups)	~/.config/hypr/scripts/quickshell
nyx	Mascot island / notch + control center (species, dock, stats)	.../quickshell/ui/nyx
palettes	Color palettes (JSON set + schema)	.../quickshell/dock/palettes
davincix	Wallpaper fetch/apply kernel	~/.local/bin/davincix
theme-sync	Cross-app theme regeneration	~/.local/bin/theme-sync
timex	Time & weather engine (providers, calendar popup UI, settings tab)	engine ~/.local/share/equisdots/timex + ~/.local/bin/timex; UI → .../quickshell/ui/timex
xturing	Terminal UI (ratatui) for the settings panel: every option of SUPER+SHIFT+D, search palette, mouse/touch	~/.local/bin/xturing (built with cargo; cache in ~/.cache/equisdots/xturing-build)
login	Static minimal SDDM greeter	/usr/share/sddm/themes/x (one-time, dots system)

Repos are cloned under ~/.local/share/equisdots/<repo>.

Usage

git clone https://github.com/equisdots/dots.git
cd dots
./dots setup       # EVERYTHING: system stack (sudo) + user payload, one run
./dots system      # packages, fonts, login theme, PAM, external configs (sudo)
./dots install     # clone/update every repo and place it (also installs `dots`)
./dots doctor      # check dependencies, clones, installed paths and plugin id integrity
./dots list        # repo status (clean / dirty / missing)
./dots plugins     # install and manage plugins (add/remove/available/list/...)
./dots update      # pull everything and re-apply
./dots reset       # forced clean reinstall of the payload (user data kept)
./dots uninstall   # remove the created links and the updater timer

dots install also drops a ~/.local/bin/dots wrapper, so after the first run the dots command is available from anywhere.

install never deletes your live config: it copies over it and keeps your settings.json untouched. For a full purge you must remove ~/.config/hypr yourself.

dots reset is the escape hatch for a bad install: it deletes the managed files (Hyprland config/scripts, shell, app configs) and the managed clones, then reinstalls everything from the latest origin/main and re-applies the active palette. It never touches your data: settings.json, config/ overrides, wallpapers/, the palette store (dock/palettes, including community and editor edits), display-config, idle-settings.json and the hyprland-backup-* snapshots survive. It also recovers dirty managed clones, which block their payload during update/install. The system stack (sudo) is out of scope: run dots system for packages, fonts, login theme and PAM.

Both install/update/reset normalize a leading ~ in settings.json's wallpaperDir to an absolute path, so the wallpaper picker always finds the collection (a literal ~ left the grid empty and failed every apply with File not found).

Plugins

The desktop supports pluggable features (the equisdots plugin standard: manifests, folders and contracts in equisdots/plugins → docs/plugins.md). Installed plugins are discovered from ~/.config/hypr/plugins (managed) and ~/.config/hypr/plugins-user (user) and show up in Settings → Plugins with an enable/disable toggle. From the CLI:

./dots plugins                  # installed: id, name, version, type, state
./dots plugins available        # registry: every known plugin (installed/available)
./dots plugins add <id>         # fetch + deploy by convention + enable
./dots plugins remove <id>
./dots plugins enable <id>
./dots plugins disable <id>

Plugins install from the registry (equisdots/plugins → registry.json): dots plugins add <id> resolves the source (owner/repo + optional path), fetches it, deploys it by the standard convention (UI face into the shell tree, runtime subset into ~/.config/hypr/plugins/<id>/) and enables it; compat is enforced (--force overrides). Plugins that declare standalone entries get a root-level launcher (plugin-<id>-<entry>.qml) so their standalone QML runs with the shell tree as the config root. Settings → Plugins lists the available ones too (with an Install button), reading the registry copy that dots deploys into the shell tree.

dots install/update also deploys the default plugins (DEFAULT_PLUGINS: screenshots — Print binds + overlay + recording; timex — calendar/weather panel + bar island; rss-reader — feed reader panel; clipboard; quicknotes; file-search; sysmon — CPU/RAM bar island, its floating monitor is opt-in) through the same convention without touching the toggle, so existing users keep the features.

Experimental phase: the registry and the plugin sources live on branch/experimental (override with EQUISDOTS_PLUGIN_BRANCH=main after the standard merges).

Nyx is plugin #1: dots install places its plugin.json in ~/.config/hypr/plugins/nyx/.

Fresh machine

One command (recommended):

bash <(curl -fsSL https://raw.githubusercontent.com/equisdots/dots/main/dots) setup -y

This runs the system stack (distro packages, Hack Nerd Font, login theme, /etc/pam.d/quickshell, kitty/nvim/starship configs; asks for sudo) and then the user payload (Hyprland config + scripts, shell, palettes, engines, timex UI), leaving a complete desktop. -y uses the recommended defaults and skips the 1.37 GB wallpaper pack (a minimal option is planned).

Manual equivalent, step by step:

1. dots system — runs equisdots/hyprland's installer: distro packages, Hack Nerd Font, login theme (clones equisdots/login on demand), /etc/pam.d/quickshell, kitty/nvim/starship configs from their repos. Asks for sudo. Add -y for a fully non-interactive run.
2. dots install — clones the org under ~/.local/share/equisdots and places the user payload (Hyprland config + scripts, shell, palettes, engines, timex UI). It also installs the dots wrapper and the monthly updater timer. Managed clones are read-only: interactive dots update fetches them and fast-forwards to origin/main. If a clone has uncommitted changes it is kept untouched and its payload is not deployed, so a stale checkout can never downgrade or delete live files; dots doctor flags those clones. Recover by committing/stashing the changes or by parking the clone (mv ~/.local/share/equisdots/<repo>{,.local} && dots install).
3. dots doctor — verifies binaries, repo clones and installed paths. The xwww wallpaper daemon (fork of awww) is installed by dots system from the checksum-verified prebuilt release (source fallback with rust). The hyprland installer only touches xwww when it is missing, so both dots update and dots system compare the running binary with the pinned release (the default in scripts/install-xwww.sh, overridable with XWWW_VERSION) and reinstall it when they differ; dots doctor reports the version mismatch. The standalone installer is scripts/install-xwww.sh (FORCE_XWWW=1 on the hyprland installer reinstalls an existing one blindly).

Remote install

No need to clone first — the script clones the whole org itself:

bash <(curl -fsSL https://raw.githubusercontent.com/equisdots/dots/main/dots) setup -y
bash <(curl -fsSL https://raw.githubusercontent.com/equisdots/dots/main/dots) doctor

After the first run, dots is available at ~/.local/bin/dots and every repo lives in ~/.local/share/equisdots. The requirements below must already be present. System-level steps that need sudo (packages, fonts, login theme, PAM, xwww) are handled by equisdots/hyprland's install.sh or manually.

Requirements

git, rsync, jq, hyprland and quickshell (qs), plus:

• xwww-daemon — wallpaper daemon; use x-ports/xwww (fork of awww with the extra transitions) or ./scripts/install-xwww.sh to build and install it from source
• mpvpaper — video wallpapers (davincix)
• Hack Nerd Font — UI glyphs

dots doctor reports what is missing.

License

MIT — see LICENSE.