Skip to main content
prune deletes every definition on the revision that no manifest entry claims. It is the only command in this group that removes anything, and it is the last step of making a revision genuinely declarative: after a clean prune, the revision holds exactly what the manifest says and nothing else. It is never implied by deploy. Every command in this group that lists the revision reports drift, leaves it untouched, and exits 0. That is deliberate: a definition someone else added in the browser is far more often work in progress than garbage, and a deploy that silently swept it away would be a deployment tool deleting things nobody asked it to. Drift is reported everywhere and resolved only here, only when you ask. Deletion is not recoverable through this CLI. There is no undo, no trash, and no way to re-create a deleted definition except by deploying its document again — which you only have if it was ever in your repository, and by definition drift never was.

​
Synopsis

There is no --definition. prune operates on the symmetric difference against the entire manifest — the same set deploy already reports as drift — and narrowing that to a subset would make “everything the manifest does not cover” mean something different on every run.

​
What it does

  1. Resolves the blob and revision. This is a write: status ready, phase draft or managed. A revision deploy would refuse, prune refuses too.
  2. Lists both categories of definition and computes drift against the whole manifest.
  3. Prints the full set, by category/alias, before asking anything.
  4. Confirms — interactively, or via --yes.
  5. Deletes each definition in turn and prints one line per deletion.
With no drift, it does not prompt at all:
Under --json the payload carries deleted, would_delete, confirmed, dry_run and drift, alongside the envelope’s schema_version. The prune: summary line is not part of that stream — like execute --watch’s live lines it is suppressed under --json, so the envelope stays the only thing on stdout. In --json mode, pass --yes: the payload is what a machine consumer reads, and an interactive prompt has no place in front of it.

​
The set is printed before you are asked

The summary line comes first, always, and it names every definition by category/alias rather than reporting a count. A bare alias would be ambiguous exactly where it matters most: an alias that names both a workflow and a playground definition is two distinct deletions, and a count of two beside one name would read like a bug. That line is not suppressed by -q, unlike the advisories. It is the destructive command’s statement of intent, not a warning someone can quiet down. The prompt defaults to declining. Anything but y — including a bare Enter — is a no, and a declined run deletes nothing and still exits 0. Declining is a valid answer, not a failure.

​
Confirmation, --yes, and no terminal

The third row is the one that matters for CI. A command that cannot prompt has two bad options — block forever on a pipe that will never answer, or delete unattended because nobody objected. prune does neither: it refuses, and tells you --yes is how to mean it.

​
--dry-run beats --yes

--dry-run is checked before --yes and before the prompt. Passing both is not a contradiction to resolve in favour of the more recent flag; the dry run wins:
A stronger safety guard losing to a weaker one is the single outcome here that could surprise somebody, and the cost of getting it wrong is unrecoverable. So --dry-run --yes deletes nothing, and a script that grew a --dry-run on top of an existing --yes behaves the way whoever added it expected. Unlike --dry-run on the other commands that carry it, this one is exact. The plan is the drift set, and the drift set is what the run just computed — there is no compile step whose outcome a dry run cannot predict.

​
If a deletion fails partway

Deletions are separate calls, made one at a time. If one fails, prune stops and re-raises the underlying API code with the definitions it had already deleted named in the message:
Once an unrecoverable operation has failed partway, “which of mine are gone?” is the only question worth answering, and naming the survivors would not answer it. Re-running prune is safe: the definitions that were deleted are no longer on the revision, so they are no longer drift, and the second run’s set is exactly what is left.

​
Errors

DEFINITION_LIST_TRUNCATED deserves more caution here than anywhere else. Drift is computed from a listing the platform cannot page, so a truncated listing means the set on screen may not be the whole set. It has never caused prune to delete something it should not — a definition that never appeared cannot be deleted — but it does mean a clean prune is not proof the revision now matches the manifest. See ls for what the advisory means and when it can and cannot fire. Every code above, with its remediation, is in Error codes.

​
See also