CLI Reference

This page describes the command surface implemented under cmd/.

Common Flags

These flags are defined on the individual commands that use them.

Target Selection Rules

When a command supports inventory-backed execution:

• A selector may be a host name, a group name, or all.
• Repeating --target builds a union of matches.
• Hosts are deduplicated by name.
• Omitting --target resolves all hosts when preflight.yml contains an inventory: block.
• Without embedded inventory, omitting --target resolves a local target.
• Using only local or localhost forces a local target even when inventory is available.

Top-Level Commands

preflight apply <playbook>

Apply a playbook to one local or inventory-backed target set.

Examples:

preflight apply playbooks/lobby.yml
preflight apply playbooks/lobby.yml --target lobby

Apply a staged bundle instead of resolving a playbook:

preflight apply --bundle dist/bundles/lobby-localhost-windows-amd64.zip

Command-specific flags:

preflight check <playbook>

Run the same execution pipeline as apply, but stop after Check() paths and report what would change.

preflight check playbooks/lobby.yml
preflight check playbooks/lobby.yml --target lobby

preflight plan <playbook>

Resolve and print the target-specific execution plan without running tasks.

preflight plan playbooks/lobby.yml
preflight plan playbooks/lobby.yml --target lobby

Behavior notes:

• plan does not contact targets.
• Action expansion and playbook imports are reflected in the printed output.
• facts.* expressions may remain unresolved in preview output.
• Remote Git-backed actions must already exist in the local cache and lockfile. Use preflight action fetch, check, or apply to populate uncached refs.

preflight validate <playbook>

Parse a playbook and resolve direct and nested uses: references without executing anything. In interactive terminals, --output tui renders a validation summary with resolved refs and status cards.

preflight validate playbooks/lobby.yml

preflight facts [target]

Gather facts for one or more targets through the selected output renderer.

preflight facts
preflight facts local
preflight facts --target lobby
preflight facts lobby-pc-01

Behavior:

• Use either a positional target or --target, not both.
• One resolved host prints one facts object.
• Multiple hosts print an object keyed by host name.

preflight stage <playbook>

Assemble one staged bundle zip per resolved target.

preflight stage playbooks/lobby.yml

When an inventory host declares platform, staging uses that OS and architecture without connecting to the host. Without a declaration, staging probes the selected host. See the inventory platform fields.

Command-specific flags:

action Commands

preflight action list

List available embedded and project-local actions. In interactive terminals, --output tui renders grouped action catalog cards.

preflight action info <ref>

Show action metadata, inputs, and task count.

preflight action info preflight/autologin
preflight action info preflight/windows-machine
preflight action info myorg/display-config

preflight action fetch <ref>

Fetch a remote action ref into the user cache, recursively fetch nested remote uses: dependencies, and create or update preflight.lock in the current project.

preflight action fetch github.com/myorg/actions/signage@v2.1

inventory Commands

preflight inventory list

List all hosts from the preflight.yml inventory.

preflight inventory list

plugin Commands

preflight plugin list

List discovered plugins and their initialization status.

preflight plugin info <name>

Show one plugin’s path, source directory, version, and initialization result.

secret Commands

preflight secret list

List configured repo-backed secrets from preflight.yml.

preflight secret encrypt <name>

Encrypt a plaintext value into the repo-backed secret store. The plaintext can come from a file, from standard input, or from an interactive no-echo prompt (confirmed twice). If no source flag is set and stdin is not a terminal, the command exits with an error rather than consuming piped input.

Command-specific flags:

--from-file and --from-stdin are mutually exclusive.

preflight secret edit <name>

Decrypt a configured secret to a temporary file, open it in $EDITOR, and re-encrypt it.

Command-specific flags:

preflight secret identity generate --out <path>

Generate an age X25519 identity file. The command creates parent directories, refuses to overwrite an existing file, writes the identity with restrictive file permissions, and prints the identity path plus public recipient.

Command-specific flags:

preflight secret identity recipient <path>

Read an existing age identity file and print its public recipient strings. Identity files with multiple identities produce one recipient per line in file order.

preflight secret rekey [names...]

Decrypt configured secrets and re-encrypt them to the current configured recipients. When names are provided, only those secrets are rekeyed.

Command-specific flags:

Overrides are rejected when specific secret names are supplied, because secrets.recipients and secrets.identity are project-wide defaults.

state Commands

preflight state show

Show the selected state file through the chosen output renderer.

preflight state diff <playbook>

Compare the current plan to the selected state file.

preflight state diff playbooks/lobby.yml
preflight state diff playbooks/lobby.yml --target lobby-pc-01

Command-specific flags:

Behavior notes:

• Local applies default to state/provision.json.
• Inventory-backed applies write state/targets/<host>.json.
• Inventory-backed diffs should pass the same --target context used for the host being compared.
• When multiple hosts resolve and --state-file is not set, the command prints one section per host and reads each host’s default state file.

Output Formats

When a task streams output during apply, the json renderer emits task_output events keyed by task_id and target, with the streamed lines in lines. Failed task_result events may also include an output array containing the captured task output block.

For human-readable output, the text renderer shows failure logs by default and prints logs below every completed task when --verbose is enabled. The tui renderer always shows a rolling preview of the last three streamed lines for each active task, prints captured failure logs by default, includes successful-task logs after completion when --verbose is enabled, and uses Lip Gloss cards, tables, and progress bars for plan and inspection commands.

Related Docs

• Run a playbook — when to use each run verb
• Run a playbook against remote hosts
• Inventory reference — selector resolution rules
• Error reference