Preflight

Preflight is a Windows-first configuration management CLI for managed endpoints such as kiosks, signage, exhibit PCs, and other dedicated systems. It compiles to a single static binary and is designed around idempotent modules, reusable YAML actions, and explicit execution phases.

preflight apply playbooks/lobby.yml

What It Is

Preflight is built around three layers:

• Modules are built-in or plugin-backed execution primitives.
• Actions are reusable YAML bundles of tasks with typed inputs.
• Playbooks are the top-level machine or environment declarations you run.

Every module follows the same contract:

Check() -> (needsChange, err)
Apply() -> err

That makes dry-run mode a real execution path instead of a fake preview path.

Execution Model

Runs flow through four explicit phases:

Fetch -> Plan -> Stage -> Apply

• Fetch acquires remote action refs into the local cache and records pinned SHAs in preflight.lock.
• Plan loads YAML, merges imports, resolves actions, expands tasks, and builds a DAG without contacting targets.
• Stage writes a per-target bundle containing the staged plan (task DAG), manifest, referenced plugins that pass initialization/name validation, and any bundled secrets needed for offline apply.
• Apply gathers facts, renders execution-time templates using target, facts, and env, executes tasks, and records state.

Quick Example

name: quickstart

tasks:
  - name: Apply machine baseline
    uses: preflight/windows-machine
    with:
      computer_name: LOBBY-KIOSK-01
      timezone: Eastern Standard Time

  - name: Create content directory
    become:
      user: exhibit
    directory:
      path: "C:\\Exhibits\\Content"
      ensure: present

Installation

macOS And Linux

curl -fsSL https://raw.githubusercontent.com/bluecadet/preflight/main/install.sh | sh

Windows PowerShell

irm https://raw.githubusercontent.com/bluecadet/preflight/main/install.ps1 | iex

For manual verification and source builds, see Install Preflight.

Common Commands

preflight validate playbooks/lobby.yml
preflight plan playbooks/lobby.yml
preflight check playbooks/lobby.yml
preflight apply playbooks/lobby.yml
preflight state diff playbooks/lobby.yml
preflight plugin list
preflight action list

Inventory-backed examples:

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

When preflight.yml contains an inventory: block, omitting --target fans out to all inventory hosts. Use --target local to force a local-only run.

Air-gapped flow:

preflight stage playbooks/lobby.yml
preflight apply --bundle dist/bundles/<bundle>.zip

Docs

The full docs live under docs/:

• Docs index
• Quickstart
• Run a playbook
• Run against remote hosts
• Validate a WinRM connection from macOS
• Deploy across restricted networks
• Manage secrets
• Write a plugin
• Write an action
• CLI reference
• Embedded stdlib action reference
• Built-in module reference
• Why use Preflight (and when not to)
• Architecture

Current Scope

Implemented today:

• Local execution and inventory-backed host selection
• WinRM and SSH targets
• Task-level become with inherited defaults and named-user execution via runas on Windows and sudo -u on POSIX
• Embedded, local, cached, and Git-backed action resolution
• Embedded Windows stdlib actions for machine, shell, input, quiet mode, updates, power, apps, and Git checkout sync
• User-scoped shell and input stdlib actions apply to the current execution identity; use become when you need to target a different Windows user
• Repo-backed age secrets
• Plugin discovery and plugin-backed module execution
• Bundle staging and bundle apply
• Output renderers for text, tui, and json, including streamed task output during apply plus richer TUI layouts for plan, facts, state, validate, and action inspection commands

Important current limits:

• SSH auto-detects either a Windows PowerShell or POSIX shell runtime. Windows-over-SSH supports the built-in Windows module set; POSIX-over-SSH supports directory, file, shell, wait (file_exists, port_open), and powershell when pwsh or powershell is installed. Plugin modules are not yet supported over SSH.

Build And Test

go test ./...
go test ./internal/runner/...
go vet ./...

For output and renderer work, you can preview scenarios without running a full playbook:

go run ./tools/sim list
go run ./tools/sim streaming --format tui
go run ./tools/sim streaming-multi-host --format tui --verbose
go run ./tools/sim failures --format json

Build commands:

GOOS=windows GOARCH=amd64 go build -o dist/preflight-windows-amd64.exe .
GOOS=windows GOARCH=arm64 go build -o dist/preflight-windows-arm64.exe .
go build -o dist/preflight .

License

ISC