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

The full generation contract (manifests, boot entries, restore semantics) is in generations.md. Hyprland-setup specific variables (X_HYPR_*) are documented in hyprland.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.
• ~/.local/share/x/home-gens/<id>/ — home generations (manifest, files/, files.sha256).
• /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 setup is not enough. It asks for the sudo password when the upstream script needs it.

x setup --user --online

Edit this page on GitHub