Overview/Scripts and CLI

x — CLI

x is the provisioning CLI of the x system (ADR-0003 in DECISIONS.md at the workspace root). Its implementation lives in bin/ of this repo and is installed as /usr/bin/x (symlink to /usr/share/x/bin/x) by the x-scripts package. When working from a checkout it can be invoked as bash bin/x.

Dispatch is by naming convention plus header-comment metadata, with no central registry: adding a command means adding one file in bin/.

Usage

x <command> [arguments]
x help          # or: x list, x -h, x --help

x with no arguments prints the help. The dispatcher exports X_BIN (the bin/ directory) and X_CLI=1 so subcommands know they run through the CLI.

Commands

Summaries are the x:summary headers of each file (shown by x help).

Root-only commands enforce root inside the dispatcher (see metadata below) and print an error if run as a non-root user.

Aliases

Aliases are defined with x:aliases metadata and let a single token map to a command file:

Dispatch mechanics

Resolution tries the longest file-name prefix first, then falls back to the first argument matched against x:aliases:

• x theme set nord → looks up x-theme.sh, then x-theme-set.sh; the latter exists, so nord is passed to x-theme-set.sh.
• x theme (single token) → no x-theme.sh; the alias theme on x-theme-list.sh matches.
• x nonexistent → error with help (exit 1).

The file must be executable to be resolved. The dispatcher only consumes x:summary, x:aliases and x:root; remaining arguments are forwarded to the subcommand, which validates its own arguments (x setup --help, x theme set with the wrong arity errors out, etc.).

Adding a command

Create bin/x-<group>-<verb>.sh as an executable script with metadata in the header:

#!/usr/bin/env bash
# x:summary=one line shown by x help
# x:aliases=alias1 alias2      # optional
# x:root=true                  # optional: require root to run
set -euo pipefail

X_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
# ...

• x:summary — one-line description, shown in x help and x list.
• x:aliases — optional space-separated aliases resolved against the first token.
• x:root=true — makes the dispatcher refuse to run as a non-root user.
• x:args — optional; informational only, not parsed by the dispatcher. Use it to document the expected arguments in the header.

There is no central registry and no registration step.

Environment variables

Hyprland-setup specific variables (X_HYPR_*) are documented in hyprland.md; the niri installer variables (X_NIRI_*) are documented in niri.md.

State

• ~/.local/state/x/ — user state: theme (active theme) and migrations/<name> (applied-migration markers).
• ~/.config/x/ — generated user config, e.g. theme.conf.
• /var/lib/x/ — system state: generations/<id>/ (manifests and captures) and current (current generation id); snapshots live in /.snapshots/.

The env overrides above let tests and development redirect every state/output path away from the real home (see test/smoke.sh).

x setup --online

Runs the original equisdots installer (equisdots/dots setup) from a temporary clone, then cleans up. Use it when already logged in and the offline packaged Hyprland setup is not enough. It only covers Hyprland; use the text installer's niri option for niri. It asks for the sudo password when the upstream script needs it.

x setup --user --online

Edit this page on GitHub