Deployment

Deploy and validate agent fleet configurations.

apply

Deploy agents from a YAML configuration file. The diff engine compares desired state against server state and applies only the necessary changes.

lettactl apply [options]

Options

Flag	Type	Description
--file, -f	string = agents.yml	Agent YAML configuration file
--agent	string	Deploy only agents matching this name
--match	string	Apply template config to existing agents matching glob pattern (merge semantics)
--dry-run	boolean	Preview changes without applying them
--force	boolean	Strict reconciliation — remove resources not in config
--root	string	Root directory for resolving relative file paths
--manifest	string	Write a JSON manifest with resource IDs after deploy
--skip-first-message	boolean	Skip sending the first_message on agent creation
--canary	boolean	Deploy canary copies of agents (CANARY- prefix)
--canary-prefix	string = CANARY-	Custom prefix for canary agents
--promote	boolean	Promote canary config to production agents
--cleanup	boolean	Remove canary agents after promotion
--skip-recompile	boolean	Skip automatic conversation recompilation after block changes
--fresh-context	boolean	Reset message buffer for agents that had changes (agent reads blocks fresh)
--fresh-context-tags	string	Only reset context for agents matching these tags (comma-separated, AND logic)
--fresh-context-match	string	Only reset context for agents matching glob pattern
--compact	boolean	Compact conversation history for agents that had changes applied (clears stale context)
--compact-tags	string	Only compact agents matching these tags (comma-separated, AND logic)
--compact-match	string	Only compact agents matching glob pattern
--recalibrate	boolean	Send a calibration message to agents that had changes applied
--recalibrate-message	string	Custom calibration message (overrides default)
--recalibrate-tags	string	Only recalibrate agents matching these tags (comma-separated, AND logic)
--recalibrate-match	string	Only recalibrate agents matching glob pattern
--no-wait	boolean	Fire-and-forget recalibration (don't wait for responses)

Examples

lettactl apply -f fleet.yaml

lettactl apply -f fleet.yaml --dry-run

lettactl apply -f fleet.yaml --agent my-agent

lettactl apply -f template.yaml --match 'support-*'

lettactl apply -f fleet.yaml --canary
lettactl apply -f fleet.yaml --canary --promote --cleanup

lettactl apply -f fleet.yaml --skip-recompile

lettactl apply -f fleet.yaml --fresh-context

lettactl apply -f fleet.yaml --fresh-context --recalibrate

lettactl apply -f fleet.yaml --compact

lettactl apply -f fleet.yaml --compact --recalibrate

lettactl apply -f fleet.yaml --recalibrate

lettactl apply -f fleet.yaml --recalibrate --recalibrate-message 'Your tools have been updated.'

lettactl apply -f fleet.yaml --recalibrate --recalibrate-tags 'role:support'

Notes

Block changes automatically recompile all conversations for affected agents (Letta 0.16.7+). Use --skip-recompile to opt out.

Supports declarative conversations — declare `conversations` in agent YAML with a `summary` field. They are created on apply and matched by summary on re-apply (idempotent).

validate

Check a YAML configuration file for syntax errors and schema violations without deploying.

lettactl validate [options]

Options

Flag	Type	Description
--file, -f	string	Configuration file to validate

Examples

lettactl validate -f fleet.yaml