Retrieve vs Deploy

The two directions every Metadata API operation moves in: pulling from an org, or pushing into one.

Definition

Retrieve and deploy are the two Metadata API operations everything else builds on, and the direction matters. A retrieve pulls metadata out of an org into local files, sf project retrieve start in Salesforce CLI, so the org is the source of truth and local files are updated to match it. A deploy pushes local metadata into an org, sf project deploy start, so the local files are the source of truth and the org is updated to match them. Mixing up direction is a common cause of overwritten work: retrieving from production after making local changes silently discards those changes unless source tracking or version control catches the conflict first. Change sets and the classic packaging UI are effectively deploy-only, one-directional operations scoped to a single upload. Our Salesforce CLI guide covers both commands in more depth.

In practice

How it works in Serpent

Serpent tracks which direction every change is flowing in as part of a task, so a developer never has to remember whether their next action is a retrieve or a deploy. Org comparison shows drift in both directions, what's in the org but not tracked, and what's tracked but not yet deployed, before either operation runs. See the Serpent VS Code extension for how retrieve and deploy actions surface without leaving the editor.

Common questions