Core understanding
The official Vercel MCP has no deletion capability; the optimal solution for large-scale deletion is REST API + Bearer token（DELETE /v13/deployments/{id}). The CLI is usable but has two pitfalls (see references).
Execution flow (strictly in order)
- Scan：
pnpm dlx tsx src/cli.ts scan --team-id <id> --out report.json. scan automatically performs a permission precheck (token identity + team membership + OWNER/DEVELOPER role determination), and exits directly if it does not pass; after passing, it generates a dry-run list (keep the latest 1 production per project, mark the rest as DELETE), and preflight evidence is written to the report. - Confirm: give the list summary (total count/delete count/per-project distribution + preflight identity and role) to the user for review,execution is prohibited without confirmation。
- Delete: first use
execute --limit 10for a trial run to verify the channel, and after independently rechecking success, execute in full (default concurrency 3, NOT_FOUND is treated as already deleted). - Governance：
retention --team-id <id>configure automatic expiration for all projects to prevent quota recurrence;verifyrecheck the final status.
Red lines
- Deletion is irreversible: without a dry-run list and user confirmation, execute must not be called in full; execute only accepts reports carrying PASS preflight evidence.
- Large-scale concurrent spawn of
vercelCLI to perform deletions is prohibited—it will break local credentials; scripts use fetch to connect directly to the REST API. - Projects are never deleted, only deployments; for retention exceptions (the platform automatically retains the most recent 10/20 Ready deployments and deployments with aliases), see references.
In-depth reading (load on demand)
- references/tool-landscape.md: the boundaries of the three channels MCP/CLI/API and the root causes of the CLI's two pitfalls.
- references/rest-api-playbook.md: endpoint quick reference, legal retention values, token acquisition, platform retention exceptions, 30-day recovery period.
- references/incident-2026-09-08.md: 845→27 real-world retrospective and the credential invalidation incident.