stack/docs/fleet/reference/cli.md

Fleet Control-Plane CLI

The local desired-state surface is mosaic fleet. It is distinct from the gateway-backed mosaic agent catalog and from legacy compatibility commands that act on roster v1.

Roster-v2 desired-state commands

Command	Effect	Generation	Output
mosaic fleet get <name>	Read one authoritative agent	no	One JSON object
mosaic fleet plan <create|update|delete> ...	Validate proposed CRUD and projections	required	One JSON object; no writes
mosaic fleet create ... [--dry-run] [--persisted-start]	Add desired state; default enabled/stopped	required	One JSON object
mosaic fleet update <name> ... [--dry-run]	Replace mutable agent fields	required	One JSON object
mosaic fleet delete <name> ... [--dry-run]	Remove roster member/generated projection	required	One JSON object
mosaic fleet apply ... [--dry-run]	Plan or converge projections/lifecycle	required	One JSON object
mosaic fleet reconcile ... [--dry-run]	Alias of the same convergence contract	required	One JSON object
mosaic fleet start|stop|restart [name] ... [--dry-run]	Exact one-shot lifecycle action	required	One JSON object
mosaic fleet status [name]	Observe desired/managed/runtime state	no	One JSON object
mosaic fleet verify	Strict observational drift/ownership gate	no	One JSON object
mosaic fleet doctor	Classify local drift and recovery context	no	One JSON object
mosaic fleet migrate-v1 preview ...	Non-mutating field-complete migration evidence	no	One JSON object

CRUD syntax and full payload shape are documented in agent mutations. Reconciliation syntax:

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>

get is the read/show operation for one v2 agent. Full roster parsing and semantic validation occur on every v2 mutation/reconcile path; there is no separate mutable “config store.” The executable JSON Schema and validated example provide offline structural evidence.

JSON and exit behavior

Roster-v2 CRUD and reconciler precondition failures emit { "error": { "code": "..." } } and exit non-zero. Migration preview has its own result envelope: a non-ready preview emits { "status": "blocked", "blockers": [...] } and exits non-zero rather than using the CRUD/reconciler error object. Use both exit status and command-specific state fields. A partial reconciliation result distinguishes authoritativeRoster, projections, lifecycle, recovery, and optional cleanup; it never claims automatic rollback. verify exits non-zero for drift, ownership failure, or unmanaged sessions. Sensitive legacy values, credentials, and rejected command text are never printed.

Compatibility and scope

Roster-v1 initialization, provisioning, profiles/personas, and historical fleet add/remove remain compatibility surfaces, not roster-v2 CRUD aliases. New v2 automation should use the table above. migrate-v1 preview writes nothing and has no cutover, canary, or rollback option.

mosaic agent is a separate catalog/transport surface; it does not own <MOSAIC_HOME>/fleet/roster.yaml desired state. Remote/SSH reconciliation, connector mutation, arbitrary commands/channels, secret references, and gateway convergence are rejected or outside scope.