Reference

cltv CLI

cltv is Collective's command line: switching, evaluation, caches, secrets, state and devices. Each command is declared in Nix and generated as its own executable. This reference is generated from those executables' --help, so it cannot drift from what they accept.

How commands are made

Commands are declared as a tree in pkgs/collective-scripts/cltv.nix with collective-lib's script framework. Branches are commandTrees, and leaves are bashScripts with typed options and a body:

kv = {  type = commandTree;  summary = "Manage the Collective KV store";  subcommands = {    create = {      type = bashScript;      summary = "Create a new KV store.";      opts = {        FORCE = {          short = "f";          long = "force";          switch = true;          description = "If set, overwrite any existing store";        };      };      body = ''        function main() {          ${log.info "…"}        }      '';    };  };};

From that, the framework generates:

one executable per node, named by its path (cltv-kv-create), so cltv kv create and cltv-kv-create are the same command;
option parsing with short and long forms, switches, defaults (which may be shell expressions evaluated at run time), required options and exported variables;
--help and a usage line built from the declaration, handled before the body runs, and a help command for every branch;
levelled logging helpers that respect cltv debug.

Edited commands can be tried without a system switch: cltv script run --name NAME builds the scripts package from the checkout and runs one. The same package ships about a hundred helpers beyond cltv, including the agent checkout commands, tmux and window-manager helpers, and nod for Android.

cltv system env --get name                # this machine's registry namecltv nix eval outputs -e 'registry.lists.nodes'scripts/site/cli-help.sh                  # regenerate this page's reference

Switching

`cltv switch`

Rebuild and switch the current system with logging.

cltv switch [--all] [--cores BUILD_CORES] [--cached] [--check-jobs] [--cpu-profile CPU_PROFILE] [--drain-args DRAIN_ARGS] [--fallback FALLBACK] [--flakehub] [--no-tui] [--machines MACHINES] [--max-jobs MAX_JOBS] [--drain] [--no-archive] [--no-drain] [-q | --quiet] [--remote REMOTE] [--remote-cores REMOTE_CORES] [--repin-inputs] [--retry RETRY_SECONDS] [--seed] [--skip-seed] [--skip-update] [--system-architecture SYSTEM_ARCHITECTURE] [--uac] [--update] [--update-only] [--raw] [--no-work]

Option	Default	Meaning
`--all`	false	Switch every machine discovered from the flake matrix through cltv-daemon fleet orchestration.
`--cores BUILD_CORES`	''	Cores per local derivation (0 = all), overriding --cpu-profile.
`--cached`	false	Activate the latest generation published by this machine's assigned prebuild cache instead of evaluating the flake locally.
`--check-jobs`	false	Only show a read-only snapshot of local jobs at risk during activation; do not update, rebuild or switch.
`--cpu-profile CPU_PROFILE`	''	Local build parallelism (default fast): fast = 2 jobs x 8 cores, medium = 2 x 4, slow = 1 x 2, all = no limits (auto jobs, all cores), config = this machine's Nix settings. Profile cores are capped at this machine's CPU count.
`--drain-args DRAIN_ARGS`	''	Extra flags for caco node drain, split on whitespace, for example "--interrupt-runners" or "--runner-wait-secs 600". Fleet switches forward it.
`--fallback FALLBACK`	none	With --flakehub, what to do without a newer FlakeHub generation: none (fail), missing (build normally when none is published or usable here, do nothing when it is not newer than the installed one) or always (build normally unless a newer one was activated). Also accepted as --fallback=MODE.
`--flakehub`	false	Activate the latest generation the FlakeHub machine-build workflow published for this machine (flakehub-generations branch, closure verified in FlakeHub Cache) instead of evaluating the flake locally. Refuses generations older than the installed one, like --cached.
`--no-tui`	false	Disable the fleet switch ratatui dashboard and print line updates instead.
`--machines MACHINES`		Comma-separated machine list to switch through cltv-daemon fleet orchestration.
`--max-jobs MAX_JOBS`	''	Local Nix build jobs (a number or auto), overriding --cpu-profile. With --remote and no override, 0: build only on the remote builder.
`--drain`	false	If set, drain this node through Cacophony around activation. Off by default: nothing is drained, held or parked. With it, where caco has caco node drain, the new generation is built (or, with --cached, downloaded) first, the node is drained (new work held, idle runner listeners stopped once their jobs finish, local agents checkpointed and parked), the generation is activated, and caco node undrain runs whether or not activation succeeded.
`--no-archive`	false	Skip the pre-switch nix flake archive entirely. Only safe when the privileged rebuild can fetch every private flake input itself (or they are already in the store).
`--no-drain`	false	Deprecated no-op, accepted for backwards compatibility. Not draining is now the default; pass --drain to opt in.
`-q \| --quiet`	false	If set, do not print build logs or stack traces.
`--remote REMOTE`		If set, build remotely on the given host or IP via ssh
`--remote-cores REMOTE_CORES`	4	The number of CPU cores to use on the remote builder. Only used if --remote is set.
`--repin-inputs`	false	Force the flake-input GC roots to be rebuilt even if the archive was skipped because every input was already present in the store.
`--retry RETRY_SECONDS`		If set, retry upon switch-failure after RETRY_SECONDS seconds.
`--seed`	false	If set, seed the Attic binary cache after a successful/degraded-success switch by running scripts/seed-cache. Off by default.
`--skip-seed`	false	Deprecated no-op, accepted for backwards compatibility. Skipping the Attic cache seed is now the default; pass --seed to opt in.
`--skip-update`	false	Deprecated no-op, accepted for backwards compatibility. Skipping flake input updates is now the default; pass --update to opt in.
`--system-architecture SYSTEM_ARCHITECTURE`	'x86_64-linux'	The architecture of the Collective system.
`--uac`	false	On devbox nodes, once the switch and every post-switch step have succeeded, start devbox-windows-admin in the background so its single UAC prompt appears on the Windows desktop. Nothing waits for the consent. Other systems skip it with a notice; fleet switches forward it.
`--update`	false	If set, run the always-update input parser and all flake input updates (including the work flake update). Off by default: the existing flake.lock is used as-is.
`--update-only`	false	Update and publish only inputs marked cltv:always-update, then exit without rebuilding or activating. Takes precedence over switch, cached activation, fleet and seed options.
`--raw`	false	If set, do not construct the build command. Instead run the command __COLLECTIVE_NIX_SWITCH_CMD.
`--no-work`	true	If set, skip work-specific steps (flake update of private inputs, corp SSH key and access token).

Nix

cltv nix Nix-related system management

`cltv nix cache flakehub status`

Show FlakeHub token, release, machine builds and whether this system is cached.

cltv nix cache flakehub status

`cltv nix cache prebuild status`

Show scheduled prebuild state and published machine generations.

cltv nix cache prebuild status

`cltv nix cache push`

Commit, push, and tag to trigger cache build workflow.

cltv nix cache push [-b BUMP | --bump BUMP] [-m COMMIT_MSG | --message COMMIT_MSG] [-t EXPLICIT_TAG | --tag EXPLICIT_TAG]

Option	Default	Meaning
`-b BUMP \| --bump BUMP`	patch	Version bump type: patch (default), minor, or major.
`-m COMMIT_MSG \| --message COMMIT_MSG`	'[rapid commit; squash later]'	Commit message.
`-t EXPLICIT_TAG \| --tag EXPLICIT_TAG`		An explicit tag to use instead of auto-bumping.

`cltv nix cache seed`

Push the current system's Nix closure to the self-hosted Attic cache(s).

cltv nix cache seed [-c ONLY_CACHE | --cache ONLY_CACHE] [-p STORE_PATH | --path STORE_PATH]

Option	Default	Meaning
`-c ONLY_CACHE \| --cache ONLY_CACHE`	''	Only push to this cache handle (a cache node name). Default: push to all (mirror).
`-p STORE_PATH \| --path STORE_PATH`		A specific Nix store path to push. If not set, auto-detects the current system closure.

`cltv nix cache status`

Check health of the self-hosted Attic binary caches on the tailnet.

cltv nix cache status

`cltv nix cache tag`

Push a version tag to trigger the Build & Cache Collective workflow.

cltv nix cache tag [-b BUMP | --bump BUMP] [-t EXPLICIT_TAG | --tag EXPLICIT_TAG]

Option	Default	Meaning
`-b BUMP \| --bump BUMP`	patch	Version bump type: patch (default), minor, or major.
`-t EXPLICIT_TAG \| --tag EXPLICIT_TAG`		An explicit tag to use instead of auto-bumping.

`cltv nix eval home`

Evaluate an expression in a Collective system's config root.

cltv nix eval home --expr EXPR [-d FLAKE_DIR | --flake-dir FLAKE_DIR] [--system-name SYSTEM_NAME] [--system-type SYSTEM_TYPE] [-u USERNAME | --username USERNAME]

Option	Default	Meaning
`-e EXPR \| --expr EXPR`	required	The expression to evaluate.
`-d FLAKE_DIR \| --flake-dir FLAKE_DIR`	'~/collective'	The directory containing the system flake.
`--system-name SYSTEM_NAME`	'<machine>'	The name of the Collective system.
`--system-type SYSTEM_TYPE`	'nixos'	The type of the Collective system.
`-u USERNAME \| --username USERNAME`	''	The username to operate over.

`cltv nix eval outputs`

Evaluate an expression in the Collective flake's outputs.

cltv nix eval outputs --expr EXPR [-d FLAKE_DIR | --flake-dir FLAKE_DIR]

Option	Default	Meaning
`-e EXPR \| --expr EXPR`	required	The expression to evaluate.
`-d FLAKE_DIR \| --flake-dir FLAKE_DIR`	'~/collective'	The directory containing the system flake.

`cltv nix eval system`

Evaluate an expression in a Collective system's config root.

cltv nix eval system --expr EXPR [-d FLAKE_DIR | --flake-dir FLAKE_DIR] [--system-name SYSTEM_NAME] [--system-type SYSTEM_TYPE]

Option	Default	Meaning
`-e EXPR \| --expr EXPR`	required	The expression to evaluate.
`-d FLAKE_DIR \| --flake-dir FLAKE_DIR`	'~/collective'	The directory containing the system flake.
`--system-name SYSTEM_NAME`	'<machine>'	The name of the Collective system.
`--system-type SYSTEM_TYPE`	'nixos'	The type of the Collective system.

`cltv nix gc reap zombies nod`

Reap GC-blocking zombies on nix-on-droid, including affected Herdr client bridges

cltv nix gc reap zombies nod

`cltv nix rebuild`

Rebuild the system from the given flake directory and system name.

cltv nix rebuild [-d FLAKE_DIR | --flake-dir FLAKE_DIR]

Option	Default	Meaning
`-d FLAKE_DIR \| --flake-dir FLAKE_DIR`	'~/collective'	The directory containing the system flake.

`cltv nix repair store`

Repair the Nix store

cltv nix repair store

`cltv nix revert`

Rebuild the system from the Nix store copy of the flake.

cltv nix revert

Useful for undoing a specialisation switch without picking up new changes.

`cltv nix specialise`

Switch to a system specialisation.

cltv nix specialise --specialisation SPECIALISATION

Option	Default	Meaning
`-s SPECIALISATION \| --specialisation SPECIALISATION`	required	Sets SPECIALISATION to the value provided

`cltv nix status`

Show Attic prebuild state, published machine generations and FlakeHub state.

cltv nix status

`cltv nix update inputs`

Update marked flake inputs without switching; optionally select one input or defer publishing.

cltv nix update inputs [-d FLAKE_DIR | --flake-dir FLAKE_DIR] [--input INPUT_NAME] [--no-publish]

Option	Default	Meaning
`-d FLAKE_DIR \| --flake-dir FLAKE_DIR`	'~/collective'	The directory containing the system flake.
`--input INPUT_NAME`	''	Update only this input, which must be marked cltv:always-update. Omit to update all marked inputs.
`--no-publish`	false	Leave the updated lockfile uncommitted for review; do not run git add, commit, or push.

Running and scripting

`cltv run`

Run a package (or a specific binary from it) from the current Collective system flake pkgs.

cltv run [-b BIN_NAME | --bin BIN_NAME] [-d FLAKE_DIR | --flake-dir FLAKE_DIR] [--system-name SYSTEM_NAME] [--system-type SYSTEM_TYPE]

cltv run PACKAGE [-- PACKAGE_ARGS...]: run PACKAGE's main program from the current system configuration's pkgs setcltv run PACKAGE#BIN [-- BIN_ARGS...]: run bin/BIN from PACKAGE (everything after the first '#' selects the binary)cltv run PACKAGE -b BIN [-- BIN_ARGS...]: same, selecting the binary via the --bin flag

Option	Default	Meaning
`-b BIN_NAME \| --bin BIN_NAME`	''	Run a specific binary from the package's bin/ dir. Alternatively use the PACKAGE#BIN convention.
`-d FLAKE_DIR \| --flake-dir FLAKE_DIR`	'~/collective'	The directory containing the system flake.
`--system-name SYSTEM_NAME`	'<machine>'	The name of the Collective system.
`--system-type SYSTEM_TYPE`	'nixos'	The type of the Collective system.

cltv script Build and run collective-scripts without a full system rebuild.

`cltv script run`

Build collective-scripts and run a script by name.

cltv script run --name SCRIPT_NAME [-d FLAKE_DIR | --flake-dir FLAKE_DIR] [--system-architecture SYSTEM_ARCHITECTURE]

Option	Default	Meaning
`-d FLAKE_DIR \| --flake-dir FLAKE_DIR`	'~/collective'	The directory containing the system flake.
`-n SCRIPT_NAME \| --name SCRIPT_NAME`	required	The name of the script to run.
`--system-architecture SYSTEM_ARCHITECTURE`	'x86_64-linux'	The architecture of the Collective system.

`cltv shell`

Enter the Collective devshell DEVSHELL with 'nix develop' args NIX_DEVELOP_ARGS

cltv shell [-s DEVSHELL | --shell DEVSHELL]

cltv shell -s DEVSHELL [NIX_DEVELOP_ARGS...]: Enter the Collective devshell DEVSHELL with 'nix develop' args NIX_DEVELOP_ARGS

Option	Default	Meaning
`-s DEVSHELL \| --shell DEVSHELL`	default	The name of the devshell to enter.

`cltv repl`

Enter an augmented nix-repl with preloaded Collective system environment.

cltv repl [--flake] [-p | --public]

Option	Default	Meaning
`--flake`	false	If set, open against the current flake.
`-p \| --public`	false	If set, open against the working copy of collective-public.

cltv template Project template management via flake templates

`cltv template init`

Initialise a new project from a template

cltv template init [-t TEMPLATE_NAME | --template TEMPLATE_NAME]

cltv template -t TEMPLATE_NAME: Project template management via flake templates

Option	Default	Meaning
`-t TEMPLATE_NAME \| --template TEMPLATE_NAME`		The name of the template to initialise.

System, files and secrets

cltv system Manage the current Collective system

`cltv system env`

Get information about the current Collective system environment.

cltv system env [-s COLLECTIVE_SYSTEM | --system COLLECTIVE_SYSTEM] [-g ENV_VAR | --get ENV_VAR]

Option	Default	Meaning
`-s COLLECTIVE_SYSTEM \| --system COLLECTIVE_SYSTEM`	self	The system whose env to use, or 'self' to refer to the current system.
`-g ENV_VAR \| --get ENV_VAR`		The environment variable to get. One of: - name: The name of the collective system. If COLLECTIVE_SYSTEM is 'self' then returns the current system name. Otherwise, returns COLLECTIVE_SYSTEM - type: The type of the current collective system (ignoring COLLECTIVE_SYSTEM). Returns one of: nixos, nix-darwin, or nix-on-droid - architecture: The architecture of the current collective system Returns e.g. x86_64-linux

`cltv system temperature`

List thermal-zone and hwmon temperatures with Waybar configuration paths.

cltv system temperature [-i INTERVAL | --interval INTERVAL] [-w | --watch]

Option	Default	Meaning
`-i INTERVAL \| --interval INTERVAL`	2	Refresh interval in seconds when watching.
`-w \| --watch`	false	Continuously refresh the temperature listing.

cltv file Manage files in the Collective system

`cltv file home`

Build and echo the contents of a Nix-generated file in ~

cltv file home --path CONFIG_PATH [-d FLAKE_DIR | --flake-dir FLAKE_DIR] [--system-name SYSTEM_NAME] [--system-type SYSTEM_TYPE] [-u USERNAME | --username USERNAME]

Option	Default	Meaning
`-p CONFIG_PATH \| --path CONFIG_PATH`	required	The path to evaluate rooted at home.file.
`-d FLAKE_DIR \| --flake-dir FLAKE_DIR`	'~/collective'	The directory containing the system flake.
`--system-name SYSTEM_NAME`	''	The name of the Collective system.
`--system-type SYSTEM_TYPE`	''	The type of the Collective system.
`-u USERNAME \| --username USERNAME`	''	The username to operate over.

`cltv file xdg`

Build and echo the contents of a Nix-generated file in ~/.config.

cltv file xdg --path CONFIG_PATH [-d FLAKE_DIR | --flake-dir FLAKE_DIR] [--system-name SYSTEM_NAME] [--system-type SYSTEM_TYPE] [-u USERNAME | --username USERNAME]

Option	Default	Meaning
`-p CONFIG_PATH \| --path CONFIG_PATH`	required	The path to evaluate rooted at xdg.configFile.
`-d FLAKE_DIR \| --flake-dir FLAKE_DIR`	'~/collective'	The directory containing the system flake.
`--system-name SYSTEM_NAME`	''	The name of the Collective system.
`--system-type SYSTEM_TYPE`	''	The type of the Collective system.
`-u USERNAME \| --username USERNAME`	''	The username to operate over.

cltv config Manage configs in the current Collective system

`cltv config keyboard unexpected`

Manage Unexpected Keyboard configs

cltv config keyboard unexpected [-c | --copy] [-d LAYOUTS_DIR | --layouts_dir LAYOUTS_DIR] [-l LAYOUT_NAMES | --layouts LAYOUT_NAMES] [-v | --verbose]

Option	Default	Meaning
`-c \| --copy`	false	If set, copy the layouts to the clipboard. Remaining args passed to clip.
`-d LAYOUTS_DIR \| --layouts_dir LAYOUTS_DIR`	/etc/unexpected_keyboard/layouts	The keyboard layout directory
`-l LAYOUT_NAMES \| --layouts LAYOUT_NAMES`		The keyboard layout names to show, without the .xml extension
`-v \| --verbose`	false	If set, show the layout XML as well as the name

`cltv config terminal ghostty`

Manage Ghostty config

cltv config terminal ghostty

cltv secret Manage secrets in the Collective system

`cltv secret edit`

Edit the Collective secrets YAML file with SOPS

cltv secret edit

`cltv secret get`

Output the contents of a secret to stdout

cltv secret get --secret SECRET_PATH

Option	Default	Meaning
`-s SECRET_PATH \| --secret SECRET_PATH`	required	The path to the secret in .parent.child format.

`cltv secret reinstall`

Re-run sops-nix activation to install new/updated secrets

cltv secret reinstall

State and debugging

cltv kv Manage the Collective KV store

`cltv kv check`

Check the validity of the KV store.

cltv kv check [-s STORE | --store STORE]

Option	Default	Meaning
`-s STORE \| --store STORE`	'~/.config/collective/kvstore'	The name of the KV store to use for the check operation.

`cltv kv create`

Create a new KV store.

cltv kv create [-f | --force] [-e | --return-error] [-s STORE | --store STORE]

Option	Default	Meaning
`-f \| --force`	false	If set, overwrite any existing store
`-e \| --return-error`	false	If set, exit with error if the store already exists.
`-s STORE \| --store STORE`	'~/.config/collective/kvstore'	The name of the KV store to use for the create operation.

`cltv kv get`

Get a value from a KV store.

cltv kv get [-o DEFAULT_VALUE | --or DEFAULT_VALUE] [-k KEY | --key KEY] [-s STORE | --store STORE]

If no key is specified, the entire KV store will be printed.

Option	Default	Meaning
`-o DEFAULT_VALUE \| --or DEFAULT_VALUE`		A default value to return if the key is not found.
`-k KEY \| --key KEY`		The key to get in the KV store.
`-s STORE \| --store STORE`	'~/.config/collective/kvstore'	The name of the KV store to use for the get operation.

`cltv kv rm`

Remove a value from a KV store.

cltv kv rm --key KEY [-s STORE | --store STORE]

Option	Default	Meaning
`-k KEY \| --key KEY`	required	The key to remove in the KV store.
`-s STORE \| --store STORE`	'~/.config/collective/kvstore'	The name of the KV store to use for the remove operation.

`cltv kv set`

Set a value in a KV store.

cltv kv set --key KEY --value VALUE [--no-overwrite] [-s STORE | --store STORE]

Option	Default	Meaning
`-k KEY \| --key KEY`	required	The key to set in the KV store.
`--no-overwrite`	true	If set, do not allow overwriting an existing key
`-s STORE \| --store STORE`	'~/.config/collective/kvstore'	The name of the KV store to use for the set operation.
`-v VALUE \| --value VALUE`	required	The value to set for the key in the KV store.

`cltv debug`

Enable or disable command debugging.

cltv debug [-d | --disable]

Enables debugging unless --disable is passed.

Option	Default	Meaning
`-d \| --disable`	false	Disable debugging.

Agents and the public flake

cltv pi Pi coding agent management

`cltv pi test`

Run the Pi extension test harness.

cltv pi test [-e EXTENSION | --extension EXTENSION] [-d EXTENSIONS_DIR | --extensions-dir EXTENSIONS_DIR] [-j | --json] [-v | --verbose]

Validates all .mjs extensions in the given directory can be imported,export a default function, and register against a mock Pi objectwithout errors. Optionally runs extension-specific smoke testsdefined in <extension>.test.json files alongside extensions.

Option	Default	Meaning
`-e EXTENSION \| --extension EXTENSION`		Only test a specific extension by name (without .mjs suffix).
`-d EXTENSIONS_DIR \| --extensions-dir EXTENSIONS_DIR`	'~/collective/standalone/pi/extensions'	The directory containing Pi extensions to test.
`-j \| --json`	false	Output results as JSON (for CI / caco test integration).
`-v \| --verbose`	false	Show detailed output per extension.

cltv public Manage the collective-public subtree

`cltv public install hooks`

Point this clone's core.hooksPath at scripts/git-hooks so every in-tree hook is live (per-clone, idempotent). Cheap; safe to run on every shell entry.

cltv public install hooks

`cltv public migrate`

Clean up stale submodule state after switching collective-public from submodule to subtree. Idempotent.

cltv public migrate

`cltv public pull`

Pull upstream changes from the public GitHub mirror into the collective-public/ subtree.

cltv public pull

`cltv public push`

Push local collective-public/ changes up to the public GitHub mirror (subtree push).

cltv public push

Devices

cltv apk Manage APK release watcher staging and installs

`cltv apk check`

Poll GitHub releases once, stage new APKs, and install staged APKs.

cltv apk check [-c CONFIG | --config CONFIG]

Option	Default	Meaning
`-c CONFIG \| --config CONFIG`	'~/.config/collective/apk-watcher/config.json'	Path to the nod-apk-watcher JSON config.

`cltv apk daemon`

Run the APK watcher polling loop in the foreground.

cltv apk daemon [-c CONFIG | --config CONFIG]

Option	Default	Meaning
`-c CONFIG \| --config CONFIG`	'~/.config/collective/apk-watcher/config.json'	Path to the nod-apk-watcher JSON config.

`cltv apk install`

Retry installation of all locally staged APKs.

cltv apk install [-c CONFIG | --config CONFIG]

Option	Default	Meaning
`-c CONFIG \| --config CONFIG`	'~/.config/collective/apk-watcher/config.json'	Path to the nod-apk-watcher JSON config.

`cltv apk status`

Print APK watcher status as JSON.

cltv apk status [-c CONFIG | --config CONFIG]

Option	Default	Meaning
`-c CONFIG \| --config CONFIG`	'~/.config/collective/apk-watcher/config.json'	Path to the nod-apk-watcher JSON config.

`cltv bt`

Manage Bluetooth devices

cltv bt

cltv desktop Desktop session-related management

`cltv desktop server name`

Get the desktop server name

cltv desktop server name

`cltv desktop wm name`

Get the window manager name (hyprland, sway, i3)

cltv desktop wm name