Bin Scripts

Bin Scripts Reference

All scripts in bin/ are invoked via hey .<script> (e.g. hey .lock). The dev hey resolves them from the working tree via the lib/hey symlink; the system hey resolves them from $DOTFILES_HOME/bin/ (nix store). See toolchain.md for the full resolution mechanism.

WM & Desktop Integration

Script	Description
`lock.zsh`	Unified screen lock dispatcher — routes to hyprlock/niri lock/swaylock based on active WM
`open-term.zsh`	Singleton terminal orchestrator for tmux sessions. Opens or focuses existing terminal
`clone-term.zsh`	Open a new terminal in the cwd of the currently focused window
`picker.zsh`	Grab a color from screen (hyprpicker on Hyprland, niri equivalent)
`screenshot.zsh`	Capture and optionally edit screenshots to clipboard + file. Supports region/window/output/screen
`screencast.zsh`	Record screen region to clipboard as webm/mp4/gif
`screendraw.zsh`	Toggle drawing overlay on screen
`slurp.zsh`	Select a monitor/region/window with slurp (Wayland region selector)
`get-window.zsh`	Select a window with slurp and query its metadata
`get-activeworkspace.zsh`	Return the `{ id, name }` of the currently active workspace
`set-monitors.zsh`	Enable given monitors, disable the rest. `--on`/`--off` per output
`toggle-zoom.zsh`	Toggle screen zoom (magnification) at given scale
`toggle-notifications.zsh`	Toggle do-not-disturb mode (WM-aware)

Keybindings & Launcher

Script	Description
`keybinds.zsh`	Parse `docs/keybindings.md` and display searchable rofi menu of all keybindings
`toggle-caffeine.zsh`	Toggle caffeine mode — prevents auto-suspend and auto-hibernate
`quitactive.zsh`	Kill (close) the currently selected/focused window

Media & Screen Capture Sub-commands

`osd.d/` — On-Screen Display (via `hey .osd`)

Script	Description
`osd.d/volume.zsh`	Show/adjust volume OSD
`osd.d/brightness.zsh`	Show/adjust brightness OSD
`osd.d/toggle.zsh`	Toggle mute/mic mute with OSD feedback

`scratch.d/` — Scratch Terminals

Script	Description
`scratch.d/term`	Drop-down scratch terminal
`scratch.d/emacs`	Drop-down scratch Emacs frame

Event Hooks (`hooks/`)

Invoked by hey hook <name>. Searches host-specific, WM-specific, then global hooks.

Hook	Description
`hooks/battery.zsh`	React to battery level changes (low battery warning, charge status)
`hooks/idle.zsh`	React to idle timeout (dim screen, lock, suspend)
`hooks/gamemode.zsh`	Enable/disable performance mode for gaming (CPU governor, GPU clock)

AI & LLM Tools

Script	Description
`commit-gen.zsh`	Generate conventional commit messages from staged git diff via local LLM. `--funny` for humor, `--copy` to clipboard
`roast.zsh`	AI-generated system roast from system info
`fortune.zsh`	AI developer fortune or tip of the day (`--tip` for practical tips)
`ascii-art-plot.zsh`	Generate ASCII art via LLM
`translate.zsh`	Terminal translator using local Ollama model (`translategemma`). `-s SRC -t TARGET`

Dev & System

Script	Description
`tmpfs-usage.zsh`	Scan `~/.cache`, `~/.config`, `~/.local` for actual tmpfs usage. Skips bind mounts (persist) and nix store symlinks. `-a` show all, `-t 1M` filter by threshold
`arch.zsh`	Enter the Arch Linux Distrobox container
`waydroid.zsh`	Manage Waydroid Android container — `start`, `stop`, `show`, `status`, `init`, `register`
`start-usb-test.zsh`	Boot a UEFI VM from USB device for testing (e.g. lab-nomad)
`lsiommu.zsh`	List IOMMU groups for PCI passthrough
`export-env.zsh`	Propagate env vars to systemd user services or tmux sessions
`set-monitors.zsh`	Enable/disable monitors by output name
`hypr-ws.zsh`	Manage Hyprland relative workspaces per monitor (1-9). Actions: `workspace`, `movetoworkspace`, `movetoworkspacesilent`

Media & Utilities

Script	Description
`ytdl.zsh`	Download audio from YouTube URL via `yt-dlp` to `~/downloads/music`
`qr.zsh`	Generate QR code from text/file to terminal
`scan-qr.zsh`	Scan QR code from screen region
`termcolors.sh`	Print a terminal color spectrum test pattern (24-bit true color)
`get-font.zsh`	Return the primary terminal font. `--xft` for Xft format, `-c` condensed, `-s` size only, `-n` name only
`play-sound.zsh`	Play a notification sound by name from the theme’s sound directory
`optimize.zsh`	Losslessly optimize images and PDFs. `-l` lossy, `-h` help
`screenshot.zsh`	Capture screenshots. Modes: `region`, `window`, `output`, `screen`. `-s`/`--swappy` for Swappy editor, `-o` for optimize
`fetch-daily-wallpaper.zsh`	Download daily wallpaper from `bing` (default), `nature`, `science`, or `random`
`fortune.zsh`	Display a random fortune or developer tip
`timein.zsh`	Open time.is for a given city/location
`when.zsh`	Display human-readable duration since/until a datetime

Maintenance & Diagnostics

Script	Description
`fleet-check.zsh`	Comprehensive systemd health check across the fleet. `--help` for full service table. Catches failed AND stuck (auto-restart) services
`checklist-email.zsh`	Verify email infrastructure: port 25 outbound, PTR, DKIM key, Cloudflare token, MX/SPF/DKIM/DMARC DNS records
`analyze-firefox.zsh`	Parse Firefox user.js for conflicts, anti-patterns, and performance issues. `--auto`, `--profile DIR`, `--nix HOST`
`setup-kanidm.zsh`	Interactive Kanidm bootstrap helper. Run on lab-matrix after first deploy. `--help` for step-by-step guide
`manage-email-dns.zsh`	Manage email DNS records (MX, SPF, DKIM, DMARC) via Cloudflare API

Helpers (rarely called directly)

Script	Description
`autoclicker.zsh`	Rapid auto-clicker (needs `xdotool`) — mainly for idle games
`slurp.zsh`	Wrapper around slurp for region/window/output selection. Used by screenshot/screencast/etc

Resolution & Execution Flow

hey .<script> [args...]
         │
         ▼
dispatch-1 (init.janet)
         │
    resolve() searches:
    1. hosts/$HOST/bin/<script>.{janet,zsh,sh}
    2. config/$WM/bin/<script>.{janet,zsh,sh}
    3. $DOTFILES_HOME/bin/<script>.{janet,zsh,sh}
         │
         ▼
    os/execute <script> [args] :p
    (passes environment with PATH and DOTFILES_HOME)

Dev vs System Resolution

Aspect	Dev (`hey build hey`)	System (`/run/current-system/sw/bin/hey`)
DOTFILES_HOME	Derived from `lib/hey` symlink in `JANET_TREE`	`$DOTFILES_HOME` env var (nix store path)
Script source	Working tree (`~/toolkits/.../dotfiles_dev/bin/`)	Nix store (`/nix/store/...source/bin/`)
New scripts	Available immediately after writing	Requires `hey sync` to deploy
Works from any dir	Yes (symlink-based detection)	Yes (env var)

Path Search Priority

The resolve() function searches in this order:

Host-specific: $DOTFILES_HOME/hosts/$HOST/bin/ — machine overrides
WM-specific: $DOTFILES_HOME/config/$WM/bin/ — compositor overrides
Global: $DOTFILES_HOME/bin/ — shared implementations

Each base is searched for extensions in order: .janet, .zsh, .sh, "" (no extension).