Batfiles command-line surface
Commands, accepted options, output, and exit statuses. Every command and option below is implemented; unrecognized commands and options are usage errors, as exit statuses describes.
Command overview
batfiles [global-options] <command> [command-options]
Global options may appear before or after the command name.
| Command | Purpose |
|---|---|
init | Create a repository skeleton or add missing installer stubs |
version | Print the installed version |
update | Check for or install a binary release |
clone | Clone a leaf repository, adopt bootstrap choices, and sync |
sync | Materialize remotes and execute selected actions |
apply-action, apply-group | Execute a named part of the manifest |
enable-action, disable-action, enable-group, disable-group | Persist machine-local selections |
vars set, get, unset | Manage machine-local variables |
vars list | Inspect effective values and origins |
vars refresh | Refresh cached dynamic variables |
Shared reference: execution options, output, selection, dry-run, partial plans, failures.
Global options
These options are accepted by every command, although a command only uses the
locations relevant to its work. init, for example, operates on the current
directory and does not use any selected roots.
| Option | Purpose |
|---|---|
-v, --verbose | Increase diagnostic detail. May be repeated, such as -vv. |
-q, --quiet | Suppress informational output and leave errors or explicitly requested data. Mutually exclusive with --verbose. |
--color <auto|always|never> | Control colored output. Defaults to auto; see color selection. |
--batfiles-dir <path> | Select the leaf repository. See location selection for its fallbacks. |
--home-dir <path> | Select the destination home directory. Defaults to the current user’s home directory. |
--config-dir <path> | Select the directory containing vars.toml and disabled.toml. Defaults to the XDG config location. |
--cache-dir <path> | Select the directory containing dynamic-vars.toml and the run lock. Defaults to the XDG cache location. |
--state-dir <path> | Select the directory containing runs.toml. Defaults to the XDG state location. |
-v prints the roots the command resolves, unchanged destinations, and action
headings and exclusions. -vv also prints the effective variables.
See location selection for which roots
each command uses and their precedence, and output streams
for quiet mode.
Shared action execution options
These options are accepted by every command that executes actions: sync,
apply-action, apply-group, and clone, which forwards them to its follow-up
synchronization.
| Option | Purpose |
|---|---|
--var <key=value> | Set a one-shot variable. Repeatable; the last value for a key wins. |
--refresh-vars | Capture every dynamic variable again, even where its cached value is fresh. |
--refresh-content | Install copies and fetched seeds again over what is at their destinations. |
--no-overwrite | Skip anything in a destination’s way instead of backing it up and replacing it. |
--interactive | Ask at each destination in the way: back up and replace, overwrite, or skip. |
A --var key must be a variable name; an invalid
key is a usage error before roots are resolved or files read. An empty value,
such as --var profile=, overrides lower layers. See
variable precedence.
--refresh-vars forces captures for the declarations this run evaluates; see
cache evaluation.
Conflicts and backups defines destination
handling and its output. --no-overwrite and --interactive are mutually
exclusive, and --interactive cannot accompany --dry-run.
--refresh-content affects only copy, copy-dir, fetch-file, and
fetch-archive; see refreshing seeds.
Output streams
| Stream | Content | Effect of --quiet |
|---|---|---|
| Standard output | Requested data: version, vars get, vars list, update --check; the standard output of run actions’ commands | None for requested data; disconnects commands’ standard output |
| Standard error | Changes, progress, prompts, warnings, errors | Suppresses informational lines; keeps warnings and errors |
Requested data has no labels or color. Errors and warnings raised by batfiles
use error: and warning: labels, colored bold red and bold yellow when
color is enabled. Verbose detail is unlabeled.
Dynamic commands inherit standard error unless --quiet disconnects it; their
output is otherwise captured or discarded. See
dynamic-command execution.
Sync and apply commands print no requested data, so a run
action’s command inherits both streams
directly and its output never mixes with batfiles’ own. Under --quiet its
standard output is disconnected and its standard error kept.
Selecting what a run does
Selection preserves declaration order. sync considers all actions; apply
commands consider the named action or group. Exclusions come from:
- Persistent disables.
- Run-only skips: CLI options and environment lists.
- The record’s condition.
- For included records, the inclusion’s filters, checked before all other exclusions.
CLI and environment skips form a union, as do skips and persistent disables. Action and group namespaces are separate. An unnamed action can be selected by its group; an ungrouped action by its ID. Identified clone-list entries belong to the action namespace; groups reach entries only through the parent list. Excluding an inclusion leaves its whole manifest unread.
Malformed run-only addresses warn when inputs are read. Well-formed skips matching nothing warn after expansion and clone-list preparation, before any action executes. Both permit continuation. A name within an unread inclusion or list is neither matched nor unmatched, and does not warn. Persistent names matching nothing are always silent.
Selection by command
| Exclusion source | sync | apply-action | apply-group |
|---|---|---|---|
| An inclusion’s selection filters | Honor | Honor | Honor |
| Disabled action IDs | Honor | Waive | Honor |
| Disabled groups | Honor | Waive | Waive the named group; honor others |
--skip-action / BATFILES_SKIP_ACTIONS | Honor | Option rejected; environment ignored | Honor |
--skip-group / BATFILES_SKIP_GROUPS | Honor | Option rejected; environment ignored | Option rejected; environment ignored |
The action’s when / unless | Evaluate if otherwise selected | Do not evaluate | Evaluate if otherwise selected |
A run action’s trigger | Honor | Waive | Honor |
A contributed run action’s missing allow-commands | Honor | Honor; naming the action fails | Honor |
clone follows the sync column. Waivers affect only this invocation and never
edit persistent state. apply-action does not evaluate the named record’s
condition even if it would fail.
Naming a child does not waive its container’s exclusions. A qualified target
opens its enclosing inclusion or clone list only if that container passes
sync’s rules, including disables, accepted run-only skips, and its condition.
An excluded container remains unread and fails the target naming the reason:
error: action `corp.zshrc` would come from include-remote `corp`, which is excluded: group `work` is disabled
error: entry `zsh-plugins.p10k` would come from git-clone-list `zsh-plugins`, which is excluded: action `zsh-plugins` is disabled
This includes a list excluded by inclusion filters: its entries cannot resolve. A contributed action whose own record is filtered out still resolves but applies nothing.
Conversely, naming a list waives none of its entries’ exclusions; each entry
uses the table under its own address. Naming one entry with apply-action
waives only that entry’s exclusions. An apply-group target reaching an
inclusion reaches its contributed actions, but waives only the requested group:
a contributed action whose own group is disabled is still left out, so
apply-group --group work passes over the actions in a disabled corp.shell.
All three commands read the leaf manifest and disabled.toml, even when they
waive lists. Missing state is empty; missing manifests and unreadable or
malformed documents fail before action execution. Variable loading follows
precedence.
Only sync materializes remotes; apply commands
use existing trees. Every command evaluates remote conditions, and none waives
them: sourcing an excluded remote fails. Only sync reports the remote’s
exclusion as skipped materialization work.
Clone-list preparation
After the run’s list is expanded and selection and action conditions are settled, all selected, unskipped clone lists are read and validated before any action writes. This includes a list read only because the command names one of its entries, and the lists an inclusion contributed, each read from the materialization its record came from. Skipped lists are not opened. A missing or malformed executable list fails the run before installation begins, even if its action appears later in the list. A list produced by an earlier action in the same run is therefore unavailable for preparation.
Preparation decides each entry as selection decides a record — its disable, then the run-only skips, then its condition, evaluated only for an entry nothing else excludes — but the exclusions are reported when the parent action runs, in list order. It comes before run-only skips are checked for a match and before an apply command’s target is resolved, since an entry’s address is known only once its list has been read.
Addresses
An address is a nonempty sequence of IDs joined
by ., with no segment-count limit. It is used wherever actions or groups are
named, including skips, apply targets, persistent choices, and bootstrap defaults.
| Form | Meaning |
|---|---|
<action-id> | Leaf action |
<group> | Leaf group |
<inclusion>.<action-id> | Contributed action |
<inclusion>.<group> | Contributed group |
<list>.<entry-id> | Entry in a leaf clone list |
<inclusion>.<list>.<entry-id> | Entry in a contributed clone list |
Unqualified names search only the leaf. <inclusion> is the inclusion record’s
ID, which can differ from its remote’s ID. Without an inclusion ID, contributed
content runs but cannot be addressed. An entry likewise needs both its own ID
and an addressable list. Entries have no group addresses.
Unique action IDs disambiguate two-segment forms: zsh-plugins.p10k is an
entry if zsh-plugins is a list, a contributed action if it is an inclusion.
Reaching into either follows container selection.
Syntax and resolution are separate. Empty or invalid segments are malformed;
a valid address matching no supported form, such as a.b.c.d.e, is simply
not found. Commands storing addresses accept such names without resolving them.
Exclusion reporting
Expected exclusions appear only at -v, in the action heading:
create-dir zsh-cache (group shell) - skipped: group `shell` is disabled
symlink zshrc (group shell) - skipped: `zshrc` from --skip-action
symlink gitconfig-work (group git) - skipped: when "work" is false
symlink corp.p10k (group corp.prompt) - skipped: not selected by include-remote `corp`
Only the first applicable reason is reported, in this order: inclusion filters, persistent disables, run-only skips, then the condition. Among the disables, and among the skips, the action’s own address comes before its group. A skip names the option or environment variable responsible, and a condition is quoted as written. A record excluded for another reason never has its condition evaluated.
A contributed run action whose remote lacks
allow-commands is excluded with a
warning, at every verbosity, after the inclusion’s filters and before the other
reasons:
warning: run corp.setup - skipped: remote `corporate` does not set `allow-commands = true`, so the `run` actions it contributes do not run
A run action that is selected but whose trigger
does not fire is not excluded: -v prints not run: and the reason under its
heading.
A condition that cannot be evaluated
warns at every verbosity, without the - skipped: frame. The warning identifies
the record, condition, failure, and remedy, without revealing the offending value.
Clone-list exclusions appear under their parent in entry order. Unrequested entries are silent; expected exclusions are verbose detail:
not cloning https://github.com/company/internal-zsh-tools.git (plugins.txt line 2): when "work" is false
not cloning https://github.com/romkatv/powerlevel10k.git (id=p10k, plugins.txt line 3): action `zsh-plugins.p10k` is disabled
Failed entry conditions warn in the same not cloning frame and leave other
entries eligible. Remote exclusions appear before actions under remote <id>:
ordinary condition exclusions at -v, evaluation failures as warnings. Neither
stops the run, but an action sourcing that excluded remote fails naming it and
repeating the reason.
Dry-run behavior
A dry run inspects the real filesystem and reports intended work without creating, replacing, or removing installation content. Each action sees the original filesystem; earlier reported writes are not simulated.
Bookkeeping still runs, including the run lock and
dynamic-variable evaluation.
Templates are evaluated, and
reports show their resolved values.
Dynamic commands are arbitrary programs and can themselves change files or
contact the network. A github-release
declaration makes its lookup’s network request in a dry run too. Captures of
both kinds are saved in the cache. A
run action’s command is never launched, and
runs.toml is left untouched.
Reports use would link, would copy, and similar wording, in the same order
and granularity as a real run: one line per child for directory-wide actions,
one for a whole installed tree. Exclusion reports are identical in both modes.
| Operation | Dry-run inspection and limits |
|---|---|
| Local source | Validate presence/readability before considering the destination, even if it would be kept |
| Occupied destination | Apply the same inspection policy and report each proposed backup name; never prompt |
| Seed | Report keeping an occupied destination, or the intended copy/download |
--refresh-content | Build and fetch nothing; report the refresh that differing content would require, without testing equality |
| Git clone/update | Run no Git, including read-only commands; report cloning at a vacant destination or updating a directory |
| File/archive remote | Inspect node and stamp to decide whether to fetch, refetch, keep, or refuse |
| Source inside a remote | Read the existing materialization, however stale; fail if missing or excluded |
| Included manifest | Read the existing materialization, first verifying a permitted checkout’s origin with a local Git query; if absent, warn and mark the plan partial |
Clone-list entries are read during preparation and reported individually; refs are printed as declared without resolving them. No installation downloads or Git network requests occur. A directory cannot be classified as a usable checkout without Git, so a dry run may report an update where a real run would find a conflict. Other destination kinds are classified normally.
A dry run cannot predict write permissions, concurrent changes, download digests, or archive entries. Archives are reported as whole trees. Declared remotes are described but never materialized, and excluded remotes are not read.
Overlapping actions can produce different reports in a real run. For example,
create-dir followed by copy at the same destination reports would create
and would copy, but a real run reports created and kept. A broken symlink
that a real run clears once can be reported repeatedly in dry-run mode,
including once per child when it occupies a directory action’s container.
Plan completeness
An include-remote whose missing materialization prevents listing its actions
warns with the remote, reason, and remedy:
warning: remote `corporate` is not materialized at /home/me/dotfiles/remotes/corporate,
so what it includes cannot be listed; run `batfiles sync` to bring it down
That warning marks a partial plan. Otherwise the plan is complete, with no additional completion message. These do not make a plan partial:
- An unreached inclusion, or one excluded by a condition, disable, or skip.
- A remote whose condition closes.
- Warnings from a manifest that was read: unmatched inclusion filters, ignored nested inclusions, or ignored remote declarations.
Partiality alone does not fail a command: available actions still run or are
reported, and status is 0 absent another failure. A specifically targeted action
or group that cannot be resolved still fails.
sync materializes remotes before action execution; dry runs and apply
commands use existing trees, where missing materializations can leave a partial
plan. Materialize the remote and repeat the command to see the remaining work.
Execution failures
An action failure stops sync or an apply command with status 1. Earlier
changes remain; nothing is rolled back, and
runs.toml still records them for
after triggers. A run action with
allow-failure warns instead, and the run continues. A
failed template is an action
failure, in dry runs too. Directory-wide actions likewise stop at the first
failed child, preserving work already completed for earlier children.
Clone-list entry failures
git-clone-list processes entries independently. Something in the way of an
entry’s destination, including a directory that is not a clone, an indirect
checkout, or an incomplete clone, is a conflict
settled for that entry alone. The list warns and continues after:
- a Git subprocess that ran but failed, including clone, fetch, or update;
- a declared ref that cannot be resolved.
The warning names the repository source, list file, line number, and entry ID
when present. If the entry’s destination was backed up and could not be put
back, it also names the backup. Warnings remain visible under --quiet.
These stop the run instead: failure to launch Git, filesystem read or write
failures, failure to create the destination container, and an unanswered
--interactive question. The categories are conservative; they do not claim
that every remaining entry would fail the same way.
Recoverable entry failures do not fail the command, so status 0 can include
entries that did not clone or update, even when every entry failed. Consult the
warnings and the Git recovery policy before retrying.
Standalone git-clone failures propagate normally.
Condition evaluation failures also warn and skip the affected action or entry without making the command fail. The condition rules define this fail-closed behavior; exclusion reporting defines the action warning format.
Exit statuses
| Status | Meaning |
|---|---|
0 | Successful command, --help, or --version; may include warnings |
1 | Runtime or semantic failure; earlier work may remain |
2 | Usage error before execution; no files read or written |
Status 1 includes invalid addresses or machine-variable keys, missing or invalid
documents, unresolved apply targets, missing vars get values, refresh failures,
lock refusal, and installation/update failures. Explicit usage errors, such as
invalid --var keys or vars refresh key syntax, are called out above.
Failures before action execution leave installation destinations untouched, although cloning, remote materialization, bootstrap state, and dynamic captures may already have occurred. See execution failures for stopping behavior and warnings that permit status 0.