Command-Line Interface#

The fractal executable is the operating surface for a fractal tree. The top-level commands manage the tree as a whole — initialization, baseline commits, tree-wide pause and resume, teardown — and public sub-apps manage nodes, inter-node messaging, and iteration plans. Agents inside the tree run the same commands: every node steers itself and its children through this CLI, whether driven by an operator at a shell or by the fractal skill.

Run fractal --help (or --help on any command) for the built-in summaries; fractal --version prints the package version. fractal --install-completion installs tab-completion for the current shell, and --show-completion prints it for manual installation.

Command map#

Command group	Purpose
fractal	Tree-level operations: skill install, initialization, baseline commits, tree-wide pause and resume, teardown, and the TUI cockpit.
fractal node	Node lifecycle and management: create, start, signal, merge, delete, inspect, and retune nodes.
`fractal node time`	Time budget introspection: seconds until the next run, iteration, or step timeout (documented on the node page).
`fractal node cost`	Cost budget introspection: remaining headroom, recorded spend, and a per-node breakdown (documented on the node page).
`fractal node config`	Read and write a node’s configuration keys (documented on the node page; the key reference is Configuration).
fractal radio	Inter-node messaging: send, post, read, reply, react, and subscribe.
`fractal radio channel`	Create, delete, and list custom channels (documented on the radio page).
fractal plan	Create and list per-iteration plan files.

Conventions#

These behaviors are shared by every command; the per-command pages state only what deviates.

Errors. Core refusals print Error: <message> on stderr and exit with code 1. Argument errors raised at the CLI boundary — bad values, unknown or ambiguous node names, mutually exclusive flags, missing required options — print a usage error (Invalid value: <message>) on stderr and exit with code 2.
The caller and the target. Almost every command takes --path (default .), which identifies the caller’s worktree — the node the command runs as. Where a command acts on another node, the target is the positional NODE argument (a branch name). The one exception is fractal radio read, where --path selects the mailbox being viewed (see fractal radio).
Short names. Branch arguments on fractal and fractal node commands (node cost targets included) resolve a unique trailing segment to the full dotted branch (lexer finds main.parser.lexer). An ambiguous short name refuses with the candidate list; an unknown one refuses with No node found for branch: '<name>'. The fractal radio targets (--node) take the full branch name only.
Listings. Listing commands print a text table on a TTY and CSV automatically when piped, so scripts get machine-readable output without flags; --csv forces CSV either way. Where --json exists it prints a JSON array ([] when empty) and is mutually exclusive with --csv. Empty listings still emit the header row.
stdout and stderr. stdout is the parseable surface — UUIDs, tables, paths. Notices, warnings, routing echoes, and confirmations of defaulted options ride stderr.
Numeric caps. Every --max-* cap must be at least 0; unlimited is expressed by omitting the flag, never by a negative or sentinel value.
Durations. Duration-valued options take <number><s|m|h|d> — for example 30s, 10m, or 1h — and must amount to at least one second. Bare numbers are rejected. See Configuration.

Internal commands#

Fractal’s hidden sub-apps and the underscore-prefixed fractal node commands are internal plumbing invoked by fractal’s own scripts — the in-tmux iteration loop, node seeding, and pre-init configuration writes. They are hidden from --help and are not user surface; their effects appear to users only as the iteration loop’s normal behavior (see The Iteration Loop).