Explore guides
Plan, apply, and recover
Understand locks and ownership, update deliberately, and retain the state needed for recovery.
Inspect before applying
Plan inspects desired resources without bootstrapping managers or writing locks, manifests, or state. Required managers must already be available. Status checks recorded pins; doctor diagnoses prerequisites and backend limitations.
workstation plan
workstation status
workstation doctorSeparate inputs from local state
Commit workstation.lock with the source configuration and imports. The lock records package pins and machine targets. It is not a backup or a complete machine image.
Ownership state, pending actions, history, and original-file backups stay local. They can contain sensitive contents. Preserve them when moving or recovering a setup.
Review updates before applying
Refresh pins explicitly, review the lock diff, and apply reviewed pins with a frozen build. Upgrade combines refreshing and applying. Reproducing historical versions depends on the backend and repository availability.
workstation lock update
# Review workstation.lock in Git
workstation build --frozen-lockfile
# Refuse plans containing removals
workstation build --no-removeRemoval and partial failures
Matching pre-existing resources are adopted by default. Unclaimed adopted packages are forgotten rather than uninstalled when removed from configuration. Owned resources can be removed; overwritten files retain original backups for restoration.
Successful actions checkpoint state. A later failure does not undo earlier actions. Read the output, fix the cause, preserve state, and inspect a new plan before rerunning. History and rollback have backend-specific limits described in the source guide.