stack/docs/fleet/reference/cli.md

Fleet Control-Plane CLI

The local roster-v2 control plane is mosaic fleet.

mosaic fleet apply --expected-generation <n> [--dry-run]
mosaic fleet reconcile --expected-generation <n> [--dry-run]
mosaic fleet start [name] --expected-generation <n> [--dry-run]
mosaic fleet stop [name] --expected-generation <n> [--dry-run]
mosaic fleet restart [name] --expected-generation <n> [--dry-run]
mosaic fleet status [name]
mosaic fleet verify
mosaic fleet doctor
mosaic fleet migrate-v1 preview --source <path> --decisions <path> --observations <path>

migrate-v1 preview is non-mutating: it emits value-free v1 inventory, a canonical semantically validated v2 candidate when ready, sanitized environment dispositions, and non-executable recovery evidence. It has no write, apply, canary, or rollback option. Missing preview inputs also return one stable blocked JSON object and a non-zero exit, rather than Commander text. See the migration preview contract.

apply and reconcile use roster desired state. start, stop, and restart are exact local one-shot lifecycle effects and never persist a desired-state edit. status, verify, and doctor are observational.

Commands emit one JSON object. Handled precondition errors emit { "error": { "code": "..." } } and exit non-zero. Partial derived/lifecycle effects use explicit authoritativeRoster, projections, lifecycle, and bounded recovery fields; they never claim rollback. Any additive cleanup diagnostic also exits non-zero, even where known effects are complete: it is not a clean completion and the lock requires inspection before retry.

This control plane is separate from the gateway-backed mosaic agent catalog. It is local-only and rejects remote/connector lifecycle mutation, arbitrary command/channel/secret input, and unproven tmux ownership.