# CLI Reference This page describes the command surface implemented under [`cmd/`](https://github.com/bluecadet/preflight/tree/main/cmd). ## Common Flags These flags are defined on the individual commands that use them. | Flag | Short | Meaning | | ------------------ | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `--target` | `-t` | Host or group selector from the `preflight.yml` inventory. Repeat to build a union. When inventory is available and this flag is omitted, commands target all inventory hosts. | | `--var key=value` | `-e` | Set a variable override. Later values win. | | `--tags` | | Run only tasks that have any of the listed tags. | | `--skip-tags` | | Skip tasks that have any of the listed tags. | | `--verbose` | `-v` | Include successful task output blocks in human-readable renderers. | | `--output` | | Output format: `text`, `tui`, or `json`. | | `--concurrency` | | Maximum number of hosts to operate on in parallel. `0` means unlimited. | | `--timeout` | | Overall run timeout such as `30m` or `1h`. | | `--fail-fast` | | Stop all targets on the first failure. | | `--run-id` | | Override the auto-generated run identifier. | | `--keep-runs` | | Number of recent successful run directories to keep (default 20). | | `--max-fail-lines` | | Max lines of output to show for a failed task (default 80). | | `--color` | | Color output: `auto`, `always`, or `never`. | | `--no-color` | | Disable color output (overrides `--color`). | ## 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 ` Apply a playbook to one local or inventory-backed target set. Examples: ```bash preflight apply playbooks/lobby.yml preflight apply playbooks/lobby.yml --target lobby ``` Apply a staged bundle instead of resolving a playbook: ```bash preflight apply --bundle dist/bundles/lobby-localhost-windows-amd64.zip ``` Command-specific flags: | Flag | Meaning | | ------------------- | -------------------------------------------------------------------------------- | | `--bundle` | Apply a staged bundle zip instead of a playbook | | `--secret-identity` | Path to an age identity file for decrypting bundle secrets (requires `--bundle`) | | `--state-file` | Override the state file path | ### `preflight check ` Run the same execution pipeline as `apply`, but stop after `Check()` paths and report what would change. ```bash preflight check playbooks/lobby.yml preflight check playbooks/lobby.yml --target lobby ``` ### `preflight plan ` Resolve and print the target-specific execution plan without running tasks. ```bash 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 ` 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. ```bash preflight validate playbooks/lobby.yml ``` ### `preflight facts [target]` Gather facts for one or more targets through the selected output renderer. ```bash 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 ` Assemble one staged bundle zip per resolved target. ```bash 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](/reference/inventory/#platform-fields). Command-specific flags: | Flag | Meaning | | ------------------------------------- | -------------------------------------------------- | | `--bundle-output-dir` | Directory for generated bundle zips | | `--allow-plaintext-secrets-in-bundle` | Allow staging secrets into the bundle in plaintext | ## `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 ` Show action metadata, inputs, and task count. ```bash preflight action info preflight/autologin preflight action info preflight/windows-machine preflight action info myorg/display-config ``` ### `preflight action fetch ` 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. ```bash preflight action fetch github.com/myorg/actions/signage@v2.1 ``` ## `inventory` Commands ### `preflight inventory list` List all hosts from the `preflight.yml` inventory. ```bash preflight inventory list ``` ## `plugin` Commands ### `preflight plugin list` List discovered plugins and their initialization status. ### `preflight plugin info ` 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 ` 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: | Flag | Meaning | | -------------- | -------------------------------------------------------------------- | | `--from-file` | Read plaintext from a file | | `--from-stdin` | Read plaintext from standard input (single trailing newline trimmed) | | `--recipient` | Override configured recipients | | `--identity` | Override the identity path stored for decrypt/edit flows | `--from-file` and `--from-stdin` are mutually exclusive. ### `preflight secret edit ` Decrypt a configured secret to a temporary file, open it in `$EDITOR`, and re-encrypt it. Command-specific flags: | Flag | Meaning | | ------------- | ----------------------------------------- | | `--recipient` | Override recipients for re-encryption | | `--identity` | Override the identity used for decryption | ### `preflight secret identity generate --out ` 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: | Flag | Meaning | | ------- | ----------------------------------------- | | `--out` | Path to write the generated identity file | ### `preflight secret identity recipient ` 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: | Flag | Meaning | | ------------- | --------------------------------------------------------------------- | | `--recipient` | Override recipients for a full rekey and save them to `preflight.yml` | | `--identity` | Override the identity for a full rekey and save it to `preflight.yml` | 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 ` Compare the current plan to the selected state file. ```bash preflight state diff playbooks/lobby.yml preflight state diff playbooks/lobby.yml --target lobby-pc-01 ``` Command-specific flags: | Flag | Meaning | | -------------- | ---------------------------- | | `--state-file` | Override the state file path | Behavior notes: - Local applies default to `state/provision.json`. - Inventory-backed applies write `state/targets/.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 | Value | Behavior | | ------ | -------------------------------------------------------------------------------------------------------------------------- | | `text` | Plain human-readable renderer | | `tui` | Interactive terminal UI renderer with richer layouts for run, plan, facts, state, validate, and action inspection commands | | `json` | Newline-delimited JSON events | 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](/how-to/run-a-playbook/) — when to use each run verb - [Run a playbook against remote hosts](/how-to/remote-execution/) - [Inventory reference](/reference/inventory/) — selector resolution rules - [Error reference](/reference/errors/)