Scripts and Commands - Ziad0dev/dots GitHub Wiki

Most commands here are packaged from scripts/ with writeShellApplication (strict mode, shellcheck at build time). Editing the .sh does nothing until you rebuild — the copy on PATH is in the store. The exceptions, which run straight from the repo, are marked.

themectl

Full reference in Theming.

themectl set <name> | current | list | next | prev | reload
themectl bg [set <path> | next | prev]

DOTS_DIR overrides where it looks for the repo (default ~/dots).

`dots-*` shims

Every dots-* name below is a symlink to one script, scripts/dots-compat.sh, which dispatches on $0. They exist so the vendored Quickshell bar has a stable command vocabulary. An unknown name exits 127.

State and toggles

Command	Does
`dots-theme-set <name>`	`themectl set <name>`
`dots-theme-bg-set <path>`	`themectl bg set <path>`
`dots-toggle-idle`	Stop/start the `hypridle` user unit; prints `on`/`off`
`dots-toggle-notification-silencing`	Toggle do-not-disturb in `~/.local/state/dots/notifications.json` (the Quickshell notification service watches it)
`dots-audio-input-mute`	Toggle mute on the default PipeWire source
`dots-llm [status\|next\|off]`	Which LLM unit is running / cycle to the next / stop all (order: `llama-cpp llama-sec llama-agent llama-gemma llama-coder llama-fim ollama`)
`dots-shell lock`	`quickshell -c lock`
`dots-shell restart`	Restart the bar
`dots-shell notifications status` / `idle status`	JSON / on-off for the bar

Status (print, never fail)

Command	Prints
`dots-updates`	`1` if the locked chaotic rev differs from chaotic-nyx `HEAD`, else `0` (cached 1 h in `~/.cache/dots-updates`)
`dots-update-available`	`1` if `flake.lock` is older than 7 days, else nothing
`dots-mounts`	Space-separated names of unhealthy mounts among `/mnt/media /mnt/backup /mnt/pool1`; empty means all fine
`dots-qbt`	`<downloading> <dl B/s> <up B/s>` from the qBittorrent API, or `off`
`dots-weather`, `dots-weather-status`	One-line wttr.in summary
`dots-brightness-display`	Backlight percent (100 on a desktop with no backlight)
`dots-hw-display`	Backlight device name, if any
`dots-voxtype-model`	Current whisper model
`dots-screenrecord-filename`	Next `~/Videos/recording-<timestamp>.mp4` path

Launchers

These open a floating terminal ($DOTS_TERMINAL, default ghostty) with window class com.dots.float, as a transient systemd scope so it outlives the bar.

Command	Opens
`dots-update`	`nh os switch` in `~/dots`, waits for Enter
`dots-launch-wifi`	impala
`dots-launch-bluetooth`	bluetui
`dots-launch-audio`	wiremix
`dots-launch-or-focus-tui <cmd>`	`<cmd>` (always launches; doesn't focus an existing one)
`dots-launch-floating-terminal-with-presentation <cmd>`	`<cmd>`
`dots-tz-select`	Points at `time.timeZone` in `hosts/nixos/configuration.nix` (timedatectl can't change a declarative zone)
`dots-voxtype-config`	fzf over whisper models → `voxtype set-model`

Capture and OSD

Command	Does
`dots-capture-screenrecording`	Start recording the focused output (HEVC, desktop + EasyEffects audio) to `~/Videos` as transient unit `dots-gsr`; `DOTS_GSR_ARGS` replaces the capture flags
`dots-capture-screenrecording --stop`	Stop `dots-gsr` (SIGINT, so the mp4 is finalised)
`dots-capture-screenrecording --save-replay`	Dump the replay buffer if `gsr-replay` is armed
`dots-swayosd-client`, `dots-swayosd-brightness`	Pass through to `swayosd-client` (no-op if missing)

Adding a shim

Add a case branch to scripts/dots-compat.sh.
Add the name to shimNames in home/quickshell-rise.nix — without this the symlink isn't created.
git add -A && update.

Other packaged commands

Command	From	Usage
`voxtype`	`scripts/voxtype.sh`	`toggle` · `start` · `stop` · `status [json]` · `model` · `models` · `set-model <path>`. Models: `ggml-*.bin` in `$VOXTYPE_MODEL_DIR` (default `~/.local/share/voxtype/models`)
`dots-nightlight`	`home/quickshell-rise.nix`	`on` · `off` · `toggle` · `status`
`dots-vpn`	`home/quickshell-rise.nix`	`on` · `off` · `toggle` · `status` — Mullvad on the host
`dots-set-wallpaper <file>`	`scripts/dots-set-wallpaper.sh`	awww with a random transition; records the choice
`dots-current-wallpaper`	`scripts/dots-current-wallpaper.sh`	Print the current wallpaper path
`dots-thumb-prune`	`home/quickshell-rise.nix`	Prune picker thumbnails (weekly timer)
`nvim-synctex <line> <file>`	`home/documents.nix`	Zathura → Neovim inverse search
`fhs`	`modules/foreign.nix`	FHS bash — see Development
`dots-look`	`scripts/dots-look.sh`	`anim [pick\|list\|<name>]` · `shader [pick\|list\|off\|<name>]` · `blur [on\|off\|toggle\|status]`
`dots-songrec`	`scripts/dots-songrec.sh`	`desktop` (default) · `mic` · `history [n]`
`dots-lens`	`scripts/dots-lens.sh`	region → clipboard → lens.google.com
`dots-shot`	`scripts/dots-shot.sh`	`region`/`screen`/`window` screenshot → `~/Pictures` + clipboard + notification (Open / Edit in satty)
`dots-say`	`scripts/dots-say.py`	`[toggle\|stop] [text…]` — Kokoro TTS; only with `dots.tts.enable = true`
`dots-mono`	`scripts/dots-mono.sh`	`on` · `off` · `toggle` · `status`
`dots-usb-sound`	`scripts/dots-usb-sound.sh`	`watch` (the unit) · `on` · `off` · `toggle` · `status`
`dots-diskio`	`scripts/dots-diskio.py`	live disk I/O and dirty/writeback totals
`dots-screentime`	`scripts/dots-screentime.py`	`daemon` (the unit) · `today` · `yesterday` · `week` · `month` · `YYYY-MM-DD`
`dots-gif`	`scripts/dots-gif.sh`	`<video> [-s start] [-t seconds] [-f fps] [-w width] [-o out.gif]`
`dots-wallpapers`	`scripts/dots-wallpapers.sh`	`sync [dark\|light\|all]` · `status` · `remove`
`dots-timemachine`	`scripts/dots-timemachine.sh`	no args: pick a commit · `back` · `status` · `<commit>`

Run from the repo

Script	Usage
`scripts/git-hooks/pre-commit`	Run by git; see Workflow
`scripts/rise-upstream.sh`	Track the upstream Rise repo the bar was vendored from: `status`, `diff [file]`, `ahead [rev]`, `pin <rev>` (the pin lives in `config/quickshell/rise/.upstream-rev`)
`tests/iso-install.py`	Install the `vm` host from the ISO under QEMU and check two boots; see Getting started
`config/zen/zen-theme-link.sh`	Link `config/zen/*.css`, plus the rendered `dots-palette.css` and `dots-sites.css`, into every Zen profile's `chrome/`. `SRC` (default: the directory the script is in) / `ROOT` env override source and profile root. Launch Zen once first so a profile exists
`config/quickshell/rise/scripts/*`	Bar helpers: `codex-usage`, `opencode-usage`, `openrouter`, `qs-barctl`, `qs-kb-*`, `qs-proj`

Fish

Abbrev	Expands to
`update`	`nh os switch` (desktop) · `nh darwin switch` (mac) · `nh home switch` (minimal)
`upall`	the above + `-u`
`flakeup`	`nix flake update --flake <repoPath>`
`g` `gst` `gco` `gp` `gl`	git, status, checkout, push, pull
`tw` `tc` `tf`	`typst watch`, `typst compile`, `typstyle -i`
`lmk` `lmc`	`latexmk -pdf -pvc -interaction=nonstopmode`, `latexmk -C`
`o` `oo` `brewup`	macOS only: `open`, `open .`, brew update + upgrade

Alias / function
`ll`, `la`, `edit`	`ls -l`, `ls -la`, `sudo -e`
`dnx <files…>`	Transcode to DNxHR HQ `.mov` for DaVinci Resolve
`y`	yazi, `cd`s to where you quit
`gpu-check`	running `llama-*` units + `ollama ps`
`gpu-free`	stop every `llama-*` unit and unload Ollama's models

Fish starts in vi mode and sources the themed fzf colours.

Units worth knowing

Unit	Scope
`quickshell`	user	the bar; bound to `hyprland-session.target`
`hypridle`	user	idle → lock → DPMS
`swayosd`, `cliphist`, `dunst` + `dotsDunstTheme` (sway only)	user	session plumbing
`dots-gammastep`	user	night light (on demand)
`dots-usb-sound`, `dots-screentime`	user	USB plug sounds, app focus log
`gsr-replay`	user	replay buffer (on demand)
`dots-gsr`	user, transient	manual screen recording
`flatpak-managed-install`	user	nix-flatpak: declared apps, after each switch
`flatpak-nvidia-gl`	user	GL extension for the loaded NVIDIA driver, at login
`mpd`, `mpdris2`	user	music
`dots-ai-usage.timer`, `dots-thumb-prune.timer`, `flatpak-prune.timer`	user	housekeeping
`llama-cpp`, `llama-sec`, `llama-agent`, `llama-gemma`, `llama-coder`, `llama-fim`, `ollama`	system	LLMs, startable without sudo
`wg`, `wg-dns`, `qbittorrent`, `prowlarr`, `flaresolverr`	system	VPN namespace
`jellyfin`, `radarr`, `sonarr`, `audiobookshelf`, `calibre-web`	system	media
`restic-backups-home`	system	backup (daily timer)
`hello-page`, `hello-page-serve`	system	tailnet site
`power-profiles-daemon`, `cpu-power-limit`	system	EPP switching (bar power-profile button), RAPL limits

_{Source: docs/scripts.md}