Skip to content
Linkdrop
Links

CLI Design Guidelines

Vercel’s manual for designing command-line capabilities, commands, interaction, output, recovery, and compatibility for people and agents.

textvercel.com · Saved Nov 6, 2026

cli design, command-line interfaces, agent permissions

Principles

Meet the bar

Every command answers 4 questions, for the person at the terminal and for the script that calls it:

  1. What will it act on? The resolved team, project, and resource, shown before anything consequential happens.
  2. What will change? Broad or risky effects, shown before they happen.
  3. What happened? The real outcome (done, pending, no-op, partial, canceled, or failed), in the output and in the exit code.
  4. What next? One exact, working command, when there is a next step.

The best command is fast, keeps the common path short, asks only for what it can’t infer, and never guesses on consequential input. It behaves the same in every mode, writes stdout you can pipe, fails with errors you can act on, and never breaks a script silently.

Start with a capability

A capability is something a person or program can accomplish: deploy a project, inspect a deployment, rotate a credential, recover from a failed upload. Define it first, with its inputs, permissions, effects, result, and failures. Choose syntax last. Design first use, empty results, long work, failure, cancellation, and recovery alongside success.

Every rule in this manual follows from 7 principles:

  1. Capability first. A capability means the same thing in the CLI, API, SDK, MCP server, and dashboard.
  2. One concept, one name. One noun per concept, one verb per operation, one option per input, all from the Reference.
  3. Resolve before acting. Every consequential target is exact and verified. Missing or invalid input is never a reason to guess, create, or switch targets.
  4. Interaction, consent, and format are independent. Prompts need a TTY. --yes grants consent but supplies no data. --json selects a format and turns off prompts, but grants no consent. Piping stdout changes none of them. The one exception is compatibility: Logs and Traces Search keep their JSONL in non-interactive runs.
  5. stdout is the answer. Results go to stdout; everything else goes to stderr. Machine formats are exact contracts.
  6. Report reality. Report accepted work as accepted and partial work as partial, and make the exit code match the outcome.
  7. Protect people and data. Secrets never leak into incidental output. Destructive work requires proof of intent. Remote text is data, never instructions.

Keep these invariants

  1. Help works before authentication, configuration, or network access, and does no work.
  2. Explicit, invalid input fails. It never falls back, fuzzy-matches a mutation target, or creates a similarly named resource.
  3. Complete explicit input behaves the same with or without a terminal. Missing input fails fast in non-interactive mode.
  4. Nothing durable changes before validation and required consent, and consent covers the final, exact target and its effects.
  5. stdout holds only the requested result. Progress, prompts, receipts, and recovery never touch it.
  6. Report only what is known. Accepted work isn’t ready yet, ending a local wait doesn’t cancel remote work, and missing evidence isn’t an empty result.
  7. Secrets travel only through the channel that requested them.
  8. Retries, waits, cleanup, and collection reads are bounded. A retry never duplicates an unsafe mutation.
  9. Every outcome can be verified through a stable ID, a receipt, an inspect command, or structured data.
  10. Public contracts change deliberately, with compatibility and evidence.

Read the requirement levels

Every rule in this manual is a requirement unless it says “should” or “may”, whether it’s written as an instruction or as a statement of behavior. “Should” marks a recommended default; deviate from it only with a stated reason. “May” marks a permitted option.

The manual describes the target design. Where a shipped command still differs, its own --help shows the syntax it accepts today.

Designing commands

Command grammar

vercel <group> [<subgroup>]... <action> [<resource>] [options]
vercel projects inspect acme-web
vercel blob stores create --name assets
vercel domains add example.com --project acme-web
  • Groups are plural nouns for collections (projects, domains) or product names for product namespaces (blob, flags, env). Child collections nest under their parent: vercel firewall rules add.
  • Top-level verbs are reserved for workflows on the current directory, session, or machine: deploy, dev, link, login, setup. Bare vercel runs vercel deploy, because deploying the current directory is the CLI’s primary job. Where a directory name could collide with a command, teach the explicit path: vercel deploy ./build, never vercel build to deploy that directory.
  • Tools and feeds (api, curl, logs, changelog) are top-level and named for what they do.
  • An obvious primary resource may be positional (vercel deployments inspect <deployment>); every other resource is a named option. Named options read unambiguously in scripts and can be given in any order. Documented exceptions: a child addressed within its parent takes both in order (flags rules update <flag> <rule>), and aliases set <deployment> <alias> keeps its long-standing form. Add any other exception to the Reference before building it.
  • A standalone change is a subcommand (enable). A boolean field of add or update is an option pair (--feature, --no-feature).
  • Never fuse a verb with a noun (create-store) or pass one as a positional value (domains auto-renew example.com on). Nest the noun (blob stores create) and make the change a subcommand (domains auto-renew enable example.com).
  • The resource follows the action: vcr permissions list acme-web, never vcr permissions acme-web list.
  • A new top-level command goes into the command index first.

Choose verbs by consequence

Name an action for its consequence, and reuse that verb in the prompt, the receipt, and the structured outcome: Revoke token deploy-ci?, then ✓ Revoked, then "outcome": "revoked". The exceptions are deploy, whose receipt is its terminal status, and the fixed outcomes unchanged, accepted, staged, started, and planned, which mean the same for every verb.

Never soften a consequence (remove for a destroyed project) or overstate it (delete for a detached member).

VerbOutcomeRecovery
deleteDestroys a resource and its dataNone
removeTakes out a member or configuration entry; the thing it refers to isn’t destroyedUsually, add it again
disconnectSevers a connection to an external system; its data stays thereUsually, connect again
revokeInvalidates a credential or access; the record stays in historyNone for the credential
emptyDeletes every item and keeps the container (queue messages, blobs in a store). purge is only for cached contentNone for the items
rotateIssues a new credential and invalidates the old one. If old versions keep working, it’s create, then activateNone for the old credential
cancelAborts an in-flight or scheduled operationDepends on the operation
stopHalts a running resource so it can be started againStart it again
transferMoves ownership to another team; the current team loses accessThe new owner can transfer it back
leaveRemoves the current user from a teamA new invitation
  • Credentials use revoke when the record stays visible and invalid, and delete only when it’s removed from storage entirely.
  • dangerously- prefixes a verb whose consequence is severe and unusual (cache dangerously-delete). It takes the severe consent tier.
  • create or add depends on how the object is managed, never on its ID, nesting depth, or the word “rule”. A webhook has its own lifecycle, so it uses create; firewall rules and flag targeting rules are entries in a configuration, so they use add: vercel webhooks create, vercel firewall rules add, vercel flags rules add <FLAG>.
  • Issuing a token, signed credential, or certificate is a mutation, never a read, even when it returns a single value; it follows the credential rules.

Every other verb, and what it replaces, is in the verb reference.

Resource identity

  • Document each selector’s accepted forms (ID, name, slug, URL), uniqueness scope, and case sensitivity.
  • A selector never ends in -id: --store, not --store-id. --request-id is the one exception, because a request has no name.
  • Accept name and ID through one selector when they can’t collide; split them only when they can, or when they mean different things.
  • Resolve exactly, among the resources the caller can access. Never pick a mutation target by first match, fuzzy match, or ID prefix.
  • Persist the stable ID when a later operation must address the same instance; keep the name for display. A token’s selector is its name or ID, never its secret value.

Use the nouns everywhere, and never introduce a synonym for variety. They set human meaning; they never rename API fields, JSON keys, or config keys. In output, say “resource” only beside a concrete noun, and “target” only for a feature flag target.

Names, shortcuts & aliases

KindDefinitionExample
Canonical nameThe one form that help, examples, docs, and suggestions teachvercel deployments list
ShortcutA permanent alternative listed beside the canonical form; never deprecatedvercel list
Command aliasA permanent, accepted spelling that is never taught and shares the canonical command’s help. Only ls for every list; rm for every remove and delete; del for every delete; singular group names; and vercel removevercel project ls
Deprecated aliasA hidden old name kept through a contract change; it prints a deprecation warningvercel target

Deployments are the primary resource, so they get top-level shortcuts. vercel remove is never taught, because “remove” would soften a deletion. A singular group name behaves exactly like its plural. Any alias in the command index not listed above is deprecated.

During a migration, teach a canonical name or long option only after its parser support ships, and keep examples and recovery executable in the version the user has.

Unknown commands & extensions

  • vercel <arg> resolves to a built-in command or alias, then an extension vercel-<arg> on PATH, then an existing local path (which it deploys), then a usage error. To deploy a directory named like an extension, use vercel deploy <dir>.
  • An unknown command or option fails with at most one close suggestion and a help command.
  • Extensions never shadow built-ins. They receive argv and stdio unchanged and own their exit code. They get VERCEL_CLI_VERSION, the resolved working directory, and an authenticated local API proxy in VERCEL_API that accepts only requests carrying a per-invocation secret passed alongside it. The CLI never injects --token or stored credentials.
  • Look up extensions only in absolute PATH entries outside the project. Root help lists installed extensions without running them, and an extension’s first run prints its resolved path on stderr.
  • Help resolves the same way; an extension receives --help in its own argv.

Options & parsing

A named input is an option, whether it takes a value or is a Boolean switch; an unnamed input is a positional argument. Help, descriptions, and errors use the same terms. “Flag” is reserved for the feature flag product, and literal names (vercel flags, JSON fields, config keys) keep their spelling.

Every command accepts the global options at every depth. A global never makes a local or help operation need the network.

OptionMeaning
-h, --helpShow help for the selected command; do no work
-v, --versionPrint the CLI version
--cwd <DIR>Working directory for this invocation
-A, --local-config <FILE>Path to the project’s vercel.json
-Q, --global-config <DIR>Path to the CLI config directory (not the Global Config product)
-d, --debugRedacted diagnostic detail on stderr
--no-colorDisable color
--non-interactiveNever prompt; fail with the required inputs instead
-S, --scope <TEAM>Team to act in
-t, --token <TOKEN>Authentication token; prefer VERCEL_TOKEN
  • Define options in shared command metadata and parse from it. Never scan argv by hand.
  • Leaf commands reject unknown options and extra positionals before doing any work. Parent commands parse permissively only to route.
  • Accept full names and declared aliases only. Never infer an option or command from a unique prefix. Adding a command later changes what a prefix matches and breaks scripts that relied on it.
  • --name value, --name=value, and -x value all work. Globals work before or after the command path. -- ends option parsing; everything after it passes through literally.
  • Names are lowercase kebab-case. Positionals render as <required> and [optional]; value hints follow the selectors and value hints.
  • Booleans are presence options with --no- negation; --feature=true and --feature=false also parse.
  • Prefer one option with comma-separated values for list inputs, such as --actions foo,bar,baz, rather than --action foo --action bar --action baz. Avoid repeated options for new list inputs. Teach the comma-separated form in help and examples. Preserve existing repeated forms for compatibility.
  • List options define ordering, duplicate and empty items, whitespace handling, and how to pass a value containing a comma.
  • Each option defines its repeat behavior (append, last wins, or error) and what an empty value means. Conflicting options are a usage error before any prompt or request.
  • Validate identifiers strictly. Pass free-form text through with its special characters intact, and encode it for its destination (URL, JSON, shell).

A recurring capability always uses its standard option, and a short option means one thing everywhere.

Settings & precedence

Settings resolve highest first: option, environment variable, project configuration (vercel.json or vercel.ts, then the .vercel/ link), the CLI config directory (--global-config; ~/.vercel or the XDG location by default), built-in default.

  • An explicit invalid value, from an option or an environment variable, fails. It never falls back to a lower source: a mistyped --scope that fell back to the default team would act on the wrong team.
  • --scope that disagrees with VERCEL_ORG_ID, or --project that disagrees with VERCEL_PROJECT_ID, is a usage error. For any other option and its environment variable, the option wins.
  • VERCEL_ORG_ID alone selects a team for team-scoped work. A project pin needs both VERCEL_ORG_ID and VERCEL_PROJECT_ID, and VERCEL_PROJECT_ID alone is a usage error for any command that resolves a project. A pin resolves exactly and never writes a .vercel/ link.
  • The current team in the CLI config directory applies to reads and ordinary team-scoped commands. It never counts as choosing a team for setup: linking or creating a project needs an explicit team or a choice.
  • A detected agent that can’t prompt never uses the current team or the account’s default team. Its team comes from --scope (a scope in vercel.json counts), an app token’s own team, VERCEL_ORG_ID, the link, or the only available team, in that order. A VERCEL_ORG_ID or link that names a team it can’t access, or a VERCEL_ORG_ID that differs from an app token’s team, fails with scope_not_accessible. With no source, the first request that needs a team fails with missing_scope and userActionRequired: true. Such a run never changes the saved team: teams switch fails with agent_cannot_switch.
  • A new public variable uses the VERCEL_ prefix and is documented in help for the commands it affects, with its precedence, empty-value behavior, and persistence. SDK variables that predate this rule (BLOB_READ_WRITE_TOKEN) keep their names. Internal and test-only variables start with __VERCEL_ and never appear in help.
VariableEffect
VERCEL_TOKENAuthentication token. Preferred over --token, which appears in process lists
VERCEL_ORG_ID + VERCEL_PROJECT_IDPin the team and project without a link. A project pin needs both; never writes .vercel/
CIForces non-interactive mode
NO_COLOR / FORCE_COLORDisable or force color (precedence)
VERCEL_TELEMETRY_DISABLEDDisable telemetry
NO_UPDATE_NOTIFIERDisable update notices
VERCEL_GUIDANCE_DISABLEDDisable optional next steps and tips
VERCEL_ACCESSIBLEAccessible mode
VERCEL_COMPAT_<NAME>Restore one old behavior for one major version after a breaking change

Help & discovery

  • vercel --help, vercel -h, and vercel help show root help; vercel <path> --help, -h, and vercel help <path> show the same help at any depth.
  • A group invoked without an action shows its help and exits 0, unless it has a documented default action.
  • Help goes to stdout, exits 0, works offline, and never authenticates, links, prompts, or mutates. People and agents reach for help when something else is broken, so it has to work then. Once help is recognized, other validation is skipped.
  • Unknown paths are a usage error that names the unknown segment and points to the nearest valid group’s help.
  • --help after a -- handoff belongs to the child. Delegated commands render the same layout from metadata they expose.
  • --version at any depth prints only the version and exits 0; with --json, it prints { "version" }. --help wins when both are given.

Help is generated from command metadata, with sections in this order and empty ones omitted:

SectionContent
Usage and summary▲ vercel <full path> <args> [options], then a one-line imperative summary and any lifecycle label
CommandsImmediate children with one-line summaries; the default action marked (default); shortcuts beside canonical names
ArgumentsPositionals, when their forms need more than the usage line
OptionsCommand options, alphabetical by long name, with the short form, value hint, default, and accepted values
Global OptionsThe full list in root help; a one-line pointer everywhere else
ExamplesThe fewest verified examples that cover distinct common jobs, usually 1 to 3, including automation and risky use where relevant. Group help may omit them
NotesMaterial behavior only: stdin, streams, auth, side effects, pagination, waiting
Learn moreThe docs URL for the command or product
▲ vercel domains add <domain> [options]
Add a domain to a project

Arguments:
  <domain>                 Domain name, such as example.com

Options:
  --force                  Move the domain from another project in the same team
  --json                   Output the result as JSON
  -p, --project <PROJECT>  Project to add the domain to (default: linked project)
  -y, --yes                Confirm moving the domain when used with --force

Global Options: See `vercel --help`

Examples:
  Add a domain to the linked project
    vercel domains add example.com

  Add a domain in CI and read the result
    vercel domains add example.com --project acme-web --json

  Move a domain from another project in CI
    vercel domains add example.com --project acme-web --force --yes

Learn more: https://vercel.com/docs/cli/domains
  • Defaults read (default: VALUE); explain context-dependent defaults in words. <domain>... means one or more and [file]... zero or more, with the ellipsis right after the closing bracket.
  • Keep the summary directly under usage. One blank line separates sections; there’s none after a heading or between rows, except between examples. Entries indent 2 spaces, and example commands 4.
  • Tables are borderless. When an entry’s syntax and description don’t fit side by side, the description moves below it; syntax is never truncated or squeezed into a narrow column. Help stays legible without color at 80 columns.
  • Root help teaches discovery. It groups commands by task (deploying, domains, observability), never by Basic and Advanced, and each group heading takes the place of Commands:. Each command appears once, by its canonical name, with a short summary and any shortcut beside it; aliases keep working but aren’t listed. There’s no generic overview and no hint to run help.
  • Leaf help makes the operation executable. Help is a reference, not a tutorial or a pitch.

In rich output, section headings are bold magenta and keep their colons, so the hierarchy survives without color. The ▲ prefix and the command and option names in usage and lists are bold foreground. The introductory summary is faint, unless it states a consequence or prerequisite. Everything else, including arguments, placeholders, value hints, defaults, and descriptions, stays normal foreground: never dim, never a fixed gray. Example commands take the command color.

Examples & suggestions

These rules cover every command the CLI prints: help examples, next steps, and recovery.

  • Use canonical names and long options only. Every example parses against current metadata and is tested through the parser, never by live mutation. People copy examples verbatim, so a broken example teaches a broken command.
  • Show the fewest examples that cover distinct jobs. When input varies, show one template, and don’t follow it with the same command filled in; add a concrete example only for syntax the template can’t teach. Each example runs one real action, never [options] or enable|disable.
  • Placeholders are <UPPER_CASE>. The angle brackets already mark them for substitution, so they need no extra label. Values are synthetic (acme, acme-web, example.com), never real credentials or retired names.
  • Preserve safe context the user supplied (--scope, --cwd, --project), and quote for their shell, including PowerShell and cmd.
  • A remote value appears in a suggestion only if it matches its selector’s identifier grammar; otherwise, use a named placeholder. Suggestions never contain secrets.
  • Print one complete command per line, indented, with no $ prompt or backticks, and never hard-wrap it. Styling adds only ANSI codes, so stripping them recovers the exact command, quotes and spaces included. Documentation transcripts, like the ones in this manual, may start with $ to mark what was typed; the CLI never prints it.
  • vercel <path> --help --json prints one document on stdout: path, summary, subcommands, arguments, options (name, short form, type, value hint, default, accepted values, repeatability, deprecation), lifecycle label, and result schema. The result schema lists the guaranteed fields of the command’s JSON result with their types, and marks secret fields. A new --json command must declare one.
  • vercel help --all --json prints every command. Both come from the same metadata as human help.
  • vercel help search <query> works offline, matches summaries, nouns, and examples, and prints up to 10 canonical paths with summaries on stdout. --json returns { "commands": [{ "path", "summary" }] }. No match exits 0 with No commands match "<query>". The query is never recorded.
  • Completion suggests canonical commands, options, and enumerated values from the same metadata. Remote suggestions (projects, teams) are cached, time-bounded, and never block or prompt. Completion never runs side effects or reveals secrets.

Lifecycle labels

Labels match the dashboard. A label appears once, after the summary of the command that carries it, never stacked or repeated on subcommands. A label never excuses unsafe behavior or reveals a private command.

LabelMeaningHelpBehavior
(none)Generally availableListedContract rules apply
PreviewFeature-complete ahead of GA; minor changes possible(preview)Changes ship with release notes
BetaUsable; bugs expected; no SLA(beta: <limit>), such as (beta: output may change)Changes ship with release notes; no per-run warning
Early AccessAvailable to some teams or plans(early access: <who>)Listed only for teams that have it, from cached entitlement; its help always renders
ExperimentalMay change or disappear without noticeHidden until its gate is on, then (experimental)Gated by an internal variable or config
AlphaInternal or invite-onlyHiddenGated
DeprecatedReplaced and scheduled for removalHidden from lists; its help names the replacementWorks, and prints a deprecation warning
HiddenInternal or test-onlyNever listedFollows every behavior rule; its name may stay internal

Resolve modes independently

A TTY is a terminal connection, as opposed to a pipe or a redirected file. Each invocation has 4 settings, and each is resolved on its own; only the rules below connect them.

SettingValuesDecided by
InteractionInteractive / non-interactiveNon-interactive for --non-interactive, --json, CI, a detected agent (unless --non-interactive=false on a TTY), stdin used as payload, or stdin or stderr isn’t a TTY
FormatHuman / JSONJSON with --json. Logs and Traces Search also write JSONL when non-interactive
PresentationRich / plainPer stream: rich only on a TTY whose TERM isn’t dumb. Color has its own precedence
ConsentAsk / granted--yes, within the limits of consent
  • Commands read resolved settings from a shared helper and never check isTTY, CI variables, or agent variables themselves. Scattered checks drift, and one command that prompts in CI hangs the pipeline. Agents are detected from their harness’s environment variables.
  • A detected agent runs non-interactively, because a prompt it can’t see would hang it. Non-interactive isn’t a format: the agent still gets human output unless it passes --json, Logs and Traces Search aside. --non-interactive=false restores prompts for an agent on a TTY, never with --json, in CI, with payload stdin, or without a TTY.
  • Piping stdout drops automatic color and animation there. It never selects JSON or suppresses prompts on stderr, because someone running vercel deploy | tee deploy.log is still at a terminal and can still answer.
  • Stdin used as a payload (--value -, --file -) can’t also answer prompts.
  • Non-interactive runs keep results, receipts, warnings, and recovery, and drop prompts, spinners, and redraws. Missing input fails with an action_required error naming the input needed.
  • Accessible mode (VERCEL_ACCESSIBLE=1) serves screen readers and simple terminals: numbered choices instead of arrow-key menus, one plain line per phase instead of spinners, and no redraws. Status words and glyphs follow plain presentation. A single choice takes one number and a multiselect a list (1,3); Enter keeps valid preselected defaults, and none clears an optional multiselect. Choice prompts list cancel, and back when there’s a previous step, and text input never depends on Escape or arrow keys: Ctrl+C or EOF cancels. Before consequential work, a numbered review lets the user change an answer. The content is otherwise identical.

Ask for a real choice

Prompt only for data that can’t be inferred, a real choice between valid options, a confirmation the consequence demands, or one optional offer after the result in interactive human mode. Every prompt has an option, argument, or stdin equivalent, and the non-interactive error names it. Never ask for intent the invocation already expressed, such as Set up and deploy? after vercel deploy.

  • Ask about one concept at a time, briefly: Which team?, Project name?, Environments?.
  • Show resolved context before asking about it. After a preview, ask for the action, not the values: Link directory to project?.
  • Use a list for several choices, and add search above 10 choices. Search may be fuzzy; selection is exact. Discard stale results.
  • A searchable list has a query field above its choices, and focus is always visible. Focus starts in the query, where typing (Space included) edits it; Tab or Enter moves to the choices, and selection keys act only there. Filtering never changes what’s already checked.
  • In a multiselect, Space checks the focused choice and Enter confirms. Focused and checked look different: > [ ] Preview is focused, [x] Production is checked. A bulk action is an explicit choice naming its scope and count (Select all 8 matching projects), never a letter shortcut that would collide with typing a query. The legend shows the current keys and the selected count. An empty required selection is refused.
  • Defaults are valid and marked (default). Detected facts, defaults, and user choices look different from each other.
  • Keep hints short and relevant to the decision, beside the prompt or on the next line.
  • Mask secret input.
  • Escape and Ctrl+C cancel; Escape never means back. A multi-step flow offers a real Back choice that keeps earlier answers. A text prompt may also go back with Up, shown in its hint; in a choice list, Up only moves focus.
  • A flow of 3 or more questions summarizes the answers before the first mutation, and after success prints the equivalent non-interactive command under Run this again without prompts:. Replayed commands never contain values typed at a prompt; they use --value - or a placeholder.
  • Render prompts on stderr.

Resolve context before effects

Each command declares its context. A read never links or creates a project as a side effect.

ContextMeaning
NoneNo project needed
ProjectRequires a linked project; fails if there isn’t one
SetupMay run the link flow (vercel link)
  • Broken config is an error, reported with its file and location, without echoing secrets. It’s never treated as absent or reset. A command validates only the config sections it uses.
  • In a repository with several linked projects, a project-scoped command run outside any one project’s root, without --project, fails with ambiguous_project and lists the candidates in data.projects. It never picks the first match.
  • When a consequential command’s team or project came from VERCEL_ORG_ID or VERCEL_PROJECT_ID, or from files tracked in the repository, human output shows Team, Project, and Source rows in every interaction mode. A Git-tracked .vercel/ directory warns link_tracked; a pin that disagrees with the directory’s link warns link_pin_mismatch.
  • Local-only fallbacks (vercel dev --local) name the remote settings or services that are unavailable. Temporary resources (anonymous deployments) state their expiry and how to claim them.

Team selection governs link, teams switch, and anything else that sets a team:

  • The team comes from an explicit signal (--scope, VERCEL_ORG_ID, or the team in vercel.json), the only available team, or Which team?. With one team, skip the chooser and show a Team row. Severe work and purchases accept fewer signals.
  • The chooser lists teams that require SSO and reauthenticates only after one is chosen.
  • A non-interactive run with several teams and no signal fails with missing_scope before any discovery or change, listing the teams in data.teams.
  • Switching to the current team is outcome: "unchanged". When the directory’s link uses a different team than the new current team, warn once with link_team_mismatch.
TierExamplesInteractiveNon-interactive
OrdinaryExplicit, reversible, or narrow: adding a variable, updating a setting, a --force replacement of one target named in argvNo confirmationRuns
DestructiveData loss, access changes, purchases, many resources, taking a domain or alias from another project, transferring ownership, pausing a project, leaving a teamPreview, then …? (y/N)Requires --yes
SevereIrreversible loss of a project, team, store, or all of a resource’s dataPreview, then type the exact nameRequires --yes, the target in argv (never inferred from the link), and an explicit team (--scope or VERCEL_ORG_ID; never the link, vercel.json, or the current team) unless the user belongs to only one
  • Preview the exact target and each downstream effect on its own line. End with This cannot be undone. when the action is irreversible, or Some effects cannot be undone. when only a side effect is. When everything is reversible, add nothing.
  • Name counts, never “selected”: Remove 5 DNS records?.
  • The severe prompt is To confirm, type the <noun> name "<name>":, and the answer must match exactly. A mismatch names the expected answer (Type only the project name "acme-web".) and never accepts a different target.
  • --yes answers yes/no confirmations, nothing more. It accepts a default only when argv and local state fully determine it and help documents it as (default: X). It never chooses between ambiguous targets, supplies missing data, or overrides permissions. A script that passes --yes never acts on a target that its argv, environment, or link didn’t determine.
  • --yes in an interactive session skips a confirmation only when the inputs that its tier requires in non-interactive mode are also present: target and team for severe work; team and --amount, or the billing plan option, for a purchase. Otherwise the prompt still runs and says which inputs are missing.
  • --force overrides a refusal the command makes by default (a conflict, an existing resource) by replacing or rerunning. For one target named in argv, --force is also consent to replace it, even when the old value can’t be recovered, and the receipt shows a Replaced row. Bulk replacement, an inferred target, taking from another project, and severe actions still need --yes in non-interactive mode.
  • Consent applies to the final target. If, during env add NEXT_PUBLIC_API_TOKEN --force, the user renames the variable to API_TOKEN at a prompt, that --force doesn’t authorize overwriting an existing API_TOKEN. Resolve the final name, environments, branch, and effects, then get fresh consent or fail with a conflict. A digest of approved effects (--effects-digest) rejects a rerun whose target or effects changed.
  • Tier a command by its effect, not its name. Deleting or emptying anything that holds user data (a store, a queue, a database) is severe. Deleting an empty or configuration-only resource is destructive. Canceling one named in-flight operation is ordinary; canceling many, or anything that changes a charge, is destructive. Adding usage on the current plan is ordinary.
  • deploy --prod, promote, and rollback need no extra confirmation, and neither do flags set, flags split, and flags rollout with --environment production, because the command states the intent. That never covers taking a domain or alias from another project. An inferred target (rollback with no argument) is previewed first, and required in argv in non-interactive mode.
  • Never promise that an action is reversible. That depends on its actual effects and the recovery available. Re-adding an entry might need a secret no one kept; transferring back needs the other owner. remove, disconnect, and transfer aren’t always reversible.
  • Never confirm ordinary writes. Confirmation fatigue trains people to say yes.

Purchases & charges

A purchase starts, changes, renews, or cancels a charge: domains buy, domains renew, billing buy, upgrading or changing a plan, a paid Marketplace integration, Speed Insights Plus on a Pro project (which starts a subscription), or changing how the account pays. It is at least destructive.

Using more of what the team’s current plan covers isn’t a purchase, however that usage is billed: deploying, adding a project, enabling Web Analytics, or turning on Observability Plus for a project on a team that already has it. It’s ordinary, with no price preview or --yes. Turning on an entitlement already in an Enterprise contract isn’t a purchase either, unless it changes the subscription; its security, access, or data effects still take their own tier. Classify by the actual entitlement and charge, never the feature name. Plan limits belong to the API, and a blocked action fails with plan_limit.

Before consent, show every fact that could change a reasonable person’s decision: the price, including tax and usage-based parts when known; when charges start; which payment method is charged; what renews, and when; and whether it can be canceled or refunded, and when that takes effect. None of it may live only behind a docs link, and none of it is ever faint.

  • Except for domains (below), non-interactive purchases require --yes and an explicit team (--scope or VERCEL_ORG_ID) unless the user has only one. An immediate charge also requires --amount <USD>, the total charged now including known tax. A usage-based one instead requires the option that selects its billing plan or rate.
  • domains buy and domains renew charge a quoted fixed price, so a matching --amount is their consent, with no --yes. They still need an explicit team; a scope in vercel.json doesn’t count, because any contributor can change it. domains buy also needs --auto-renew or --no-auto-renew, because auto-renewal is a recurring charge. Without these inputs they charge nothing and fail with confirmation_required, returning the price, the renewal terms, and the command to run once a person approves.
  • A missing --yes, --amount, billing plan option, or auto-renew choice fails with confirmation_required; a missing team, with missing_scope; an amount that no longer matches the price, with price_changed. None of these charges anything.
  • Send an idempotency key when the API accepts one. The domain registrar doesn’t, so domains buy and domains renew never retry a charge, and report unknown_outcome when they can’t confirm it went through.
  • The receipt and JSON result include charge: { "amount", "currency" }. domains price --json and a purchase’s --dry-run return the exact amount to pass back.

Authentication & browser handoffs

  • Credentials resolve --token, then VERCEL_TOKEN, then stored login, and are read only when the operation needs them. Local commands never require them.
  • Without credentials, only login starts a login flow. Every other command that needs credentials fails with login_required, and non-interactive mode never opens a browser. A valid token that lacks a permission fails, naming the missing permission and how to get a suitable token.
  • When a token expires or SSO is required mid-command, interactive mode reauthenticates, then resumes reads only, never replaying a mutation that might have been sent. Non-interactive mode fails with token_expired or sso_required, and userActionRequired: true. Refreshing a stored credential takes a lock.
  • Login is one interactive flow: print the verification URL and code, open a browser as below, and wait with a bounded timeout. In non-interactive mode, the login_required error says to set VERCEL_TOKEN. logout revokes the token on the server when possible, deletes it locally, and reports each result separately.
  • Creating a credential shows its team access and expiry first, with least-privilege defaults: one team and a finite expiry. With an explicit team and expiry it’s ordinary; with no expiry, or access to every team, it’s destructive. A leaf named for what it returns (projects token) still issues a credential; it is never a query.
  • Open a browser only in interactive mode on a local desktop session, and always print the URL too. In non-interactive mode, CI, or over SSH, print the URL and the next step instead. Every command that opens a browser accepts --no-open.

Output

Give each stream one job

  • stdout carries the answer. For a query, that’s its data: tables, detail views, values. For a mutation, it’s the stdout identifier, the first form in the noun’s identity, printed bare. It prints in human format when stdout isn’t a TTY or the run is non-interactive, so url=$(vercel deploy) works. On an interactive TTY the receipt already shows it; with --json, the document replaces it.
  • A requested secret (a new token) replaces the identifier. In human format it prints alone on stdout, interactive TTY included, after any CI ::add-mask::; the stderr receipt names the credential but never shows its value.
  • link and teams switch count as mutations and print the resource they selected.
  • The stdout identifier prints only on exit 0, acceptance included. On failure, the ID goes in the error’s ID rows or data.
  • stderr carries everything else: context, receipts, progress, prompts, warnings, errors, and next steps. Animation never interleaves with stdout.

Raw API output, file bytes, a single value, and inherited child-process streams have protocols of their own. Don’t force them into a receipt or a JSON wrapper.

Design the whole transcript

Use only the phases a task needs, in this order: context (the resolved target, when it was inferred and the result depends on it), input, preview (for destructive work), work, result, next. Context and preview don’t repeat a value already visible in argv, a prompt answer, or a nearby row, unless pinned context or consent requires it: a preview always names its exact target. A receipt may repeat its target and saved values.

After work or logs, the result leads with the outcome and the primary destination, then supporting facts and a useful next step, compact enough to find above the returned shell prompt. A URL or ID that helps someone follow the work may appear earlier, under the progress line, so it reads as pending.

$ vercel dns add example.com --name www --type CNAME --value cname.vercel-dns.com
✓ Added           www.example.com
  Type            CNAME
  Value           cname.vercel-dns.com
  Record ID       rec_5hG2kx

Rich output puts result blocks, detail blocks, and status blocks on a shared gutter in columns 0 and 1: column 0 holds a glyph or a space, and content starts at column 2. Label/value rows set the label in a 16-character column and start the value at column 18, counting from zero. Help, tables, prompt choice lists, and plain output have layouts of their own, with no status gutter. Use the shared layout helpers; never hand-pad.

GutterMeaningUse
BlankContext, preview, secondary rows, progressMost rows
✓The one primary completed resultOnce per completed operation; never on discovery, pending, or queued work
▲ProductionOnce, beside the primary Production destination; never in place of the Production label
!WarningA nonfatal condition that needs attention
✗Fatal errorThe error headline
?PromptRendered by the prompt library
  • Labels are stable and have no trailing colon. Related rows are contiguous; a blank line separates phases.
  • A heading above rows is plain text (Found existing project), never a fake label/value row.
  • No emoji in primary rows. In rich output, no > prefixes (a prompt’s focus pointer aside), Error: headline prefixes, or WARNING!, Success!, or Ready! banners.
  • Plain presentation and accessible mode replace glyphs with words.

Reference transcripts

Human output on a TTY. Context, receipts, and hints go to stderr; tables go to stdout.

$ vercel deployments list
  Project         acme/acme-web

  Age   URL                                  Environment   Status   Duration
  2m    acme-web-4f2k9x1-acme.vercel.app     Production    Ready    41s
  1h    acme-web-8h3j2a0-acme.vercel.app     Preview       Error    12s

  Next page:
    vercel deployments list --next cGFnZToy
$ vercel deploy --prod
  Building…
  Deployment      https://acme-web-4f2k9x1-acme.vercel.app
  Inspect         https://vercel.com/acme/acme-web/9x1Kq2

✓ Ready in 41s
▲ Production      https://example.com
  Deployment      https://acme-web-4f2k9x1-acme.vercel.app
  Deployment ID   dpl_9x1Kq2
$ vercel projects delete acme-web
  Project         acme/acme-web

  Deletes the project and its 214 deployments.
  Removes example.com and www.example.com from the project.
  This cannot be undone.
? To confirm, type the project name "acme-web": acme-web

✓ Deleted         acme-web
$ vercel deploy --prod --non-interactive
✗ Can't deploy without a team in non-interactive mode. 3 teams are available.

  Pass the team with --scope:
    vercel deploy --prod --scope <TEAM>

The deploy transcript is interactive stderr; piped, its human result is the deployment URL alone on stdout. The early URLs sit under Building…, so they read as pending. The final block leads with the outcome, then the Production destination. The alias appears there only once the API confirms it; until then, the block keeps the deployment URL and says the alias is pending. An alias moves with each deploy, so the immutable deployment URL and Deployment ID stay beside it. Ready appears only once readiness is known; --no-wait reports the deployment as accepted, with its ID and an inspect command.

Tables, details & empty results

  • Tables show what’s needed to act on a row, including the identifier the next command takes, in a stable, documented order (usually newest first).
  • On a non-TTY stdout, tables keep the header, separate columns with one tab, never truncate or pad, and use ISO times, so grep, cut, and agents read them reliably.
  • Detail views use aligned rows under plain headings for the fields people act on. --json has the rest.
  • Never truncate the only copy of an ID, URL, path, or command. Shorten optional descriptive columns with … first. If the columns that identify a row and give its status still don’t fit, a TTY table switches to compact records, one short block per row with the same required fields. Non-TTY output keeps its tab-separated format at any width.
  • A list inside a receipt, detail view, or error shows at most 5 items, then and 12 more, then the command that lists them all.
  • Activity rows read <actor> <past-tense verb> <resource> [<qualifier>]: jane@example.com deleted project acme-web, [Vercel CI] deployed dpl_x7hB2k to Production. System actors go in brackets. Never infer a completed action from a row that records only acceptance.

An empty collection is success (exit 0). A missing parent, an ambiguous selector, denied access, or a failed request is not. In human mode the prose goes to stderr, and a non-TTY stdout gets only the table header. With --json, stdout gets the empty document and nothing else. Zero reads No deployments, never 0 deployments.

$ vercel domains list --project acme-web
  No domains in acme/acme-web.

  Add one:
    vercel domains add <DOMAIN> --project acme-web
KindCopy
No resultsOne filter: No <items> match this filter. Remove <option> to see all <items>. Several: No <items> match these filters., plus how to widen them
First useThe team or project, then the command that adds the first item: No domains in acme/acme-web.
Partial visibilityShowing projects you can access in acme.

A plan-gated or permission-denied read is an error, not an empty state.

Color, width & platform

Wording and order carry the meaning; spacing, weight, and hue only reinforce it. Output stays clear with all styling removed, so never rely on color, glyphs, or animation alone.

  • Styling goes through shared semantic roles, never raw colors or ANSI codes. Each stream resolves its own capabilities, and no command toggles styling for the whole process.
  • Bold marks the primary outcome, help headings, and command and option names in help. Values, IDs, paths, prices, and descriptions stay normal foreground.
  • Hue: green, yellow, and red mark the success, warning, and failure glyphs, and magenta marks help headings. Cyan, at normal weight, marks a complete command offered in an example or next step, on its own line. Templates with placeholders stay foreground, and a command mentioned inline stays foreground in literal backticks, never cyan.
  • Links: underline the primary destination, such as a deployment’s Production URL; other URLs are unstyled. Print URLs in full. OSC 8 may wrap them on supporting TTYs only.
  • Faint is for the help summary and truly optional metadata, never for context, consequences, prices, IDs, choices, or recovery.
  • Palette: use the terminal’s basic ANSI colors and default background, with no fixed grays, fills, or decoration, and never recolor logs or remote text. The user owns the palette, so no hue is guaranteed enough contrast in every theme.
  • Glyphs come from one shared set, with ASCII fallbacks for plain presentation and accessible mode, and ... for …. Rich success is ✓. Plain status rows start at column 0 and state the outcome as a sentence (Added API_TOKEN); warnings and errors keep their Warning: and Error: prefixes.

Color preference, highest first: --no-color, a nonempty NO_COLOR, FORCE_COLOR (0 means off), then detection per stream, which is off for pipes and TERM=dumb.

  • Turning color off removes only color; text, glyphs, layout, and streams stay the same.
  • Plain presentation, for a pipe or TERM=dumb, is unstyled. Forced color may tint only its Warning: and Error: prefixes, and help stays fully unstyled even when forced.
  • JSON, stdout identifiers, secrets, plain values, and tab-separated tables are never styled.

Measure width on the destination stream by display width, with 80 columns when it’s unknown.

  • Wrap prose to fit, and stay usable at 40 columns, never overlapping or clipping. A value that doesn’t fit beside its label moves to the next line.
  • The CLI never breaks, shortens, or alters a command, URL, ID, or path; a value longer than the line may soft-wrap in the terminal. Paths display in the platform’s native form.

Time, numbers & units

KindRule
AgesTables: relative under 7 days (2m, 5h, 3d), then absolute (Mar 5, 2026). Detail views: local time with timezone, plus age where useful (2026-09-28 14:03 PDT (2h ago)). Billing, activity, and non-TTY output: ISO 8601 UTC
DurationsCompact in tables and status lines (42ms, 3.4s, 2m 10s, Ready in 41s); spaced in sentences (42 ms)
CronThe expression and a library-generated reading: */5 * * * * (every 5 minutes)
Money$ with no space. Prices, charges, and receipts show cents ($20.00, $0.40); summaries may round ($20)
CountsNumerals with correct plurals (1 project, 3 projects), never project(s). Commas from 1,000; 12.5K only in summaries, from 10,000; exact numbers in billing
SizesDecimal units (MB); binary units (MiB) only for literal memory

Writing for the terminal

Use a calm, direct voice. Settle the behavior and its consequence first, then polish the words. Where this manual gives an exact phrase, use it verbatim; it matches the dashboard.

SurfacePatternExample
Help summaryImperative verb and object, no periodList deployments for a project
QuestionShort and concrete, ending in ?Which team?
ConfirmationAction, exact object, consequenceRevoke token deploy-ci? Deployments using it will fail.
ProgressPresent participle and …Building…
ReceiptPast-tense verb and target, in aligned rows✓ Deleted acme-web
ErrorIts class’s formulaCouldn't find project acme-wbe in acme.
Next stepBenefit and :, then the command on its own lineStream the build logs:
  • Name the thing: Connect your GitHub account, not Connect your account.
  • Use active voice, natural contractions, and numerals. Cut filler.
  • State the constraint instead of blaming the user: Names use lowercase letters, numbers, and hyphens., not You entered an invalid name.
  • Name destinations and commands, never click here or a bare Retry. Learn more: appears only as the help section label, followed by its URL.
  • Apologize only for a real Vercel fault or disruption.
AvoidWords
Hypeseamlessly, effortlessly, powerful, robust, leverage, blazing, cutting-edge, world-class, utilize, streamline
Fillerjust, simply, actually, please, in order to, at this time, it’s important to note
Vague outcomessuccessfully, Done!, OK, Unable to, An error occurred, Something went wrong
InterjectionsOops, Whoops, Uh-oh, Yay, Heads up
Vague promptsContinue?, Are you sure?, Do you want to…
Non-inclusive termswhitelist and blacklist (use allowlist and blocklist), master and slave (primary and replica), kill (stop, except for literal signals), sanity check, dummy
AI cadence“It’s not X, it’s Y”, “No X. No Y. Just Z.”, rhetorical questions, em-dash chains, tricolons for rhythm
  • Use sentence case for prose, questions, help, and statuses, and Title Case for aligned labels, table headers, and help section titles, except Learn more:. Nouns keep their preserved casing.
  • Periods end sentences, not fragments or labels. Use the Oxford comma, and … (one character) for ongoing work. Never use ! in CLI-written text; it’s only the warning glyph. User data and quoted partner messages keep their punctuation.
  • Use ASCII quotes and apostrophes, not the dashboard’s curly ones: CLI output is pasted into shells and read by consoles that can’t render them.
  • Write commands, options, paths, and values exactly. Never rewrite JSON keys, telemetry names, third-party literals, or parser values for consistency.

Next steps & tips

A next step follows from current state and appears every time that state applies.

  • Offer one, or a single Next steps: list of independent actions with required recovery first. Each states its benefit, then the command.
  • Check every suggestion against current state. While remote work might still be running, suggest checking status, never retrying.
  • Optional steps respect VERCEL_GUIDANCE_DISABLED and user settings. Required recovery always shows.

A tip (completion setup, a new feature, a better command for what the user just did) is useful once.

  • Show a tip at most once per user, recorded in the CLI config directory, and at most one per run.
  • Show it only after success, in interactive human mode with no detected agent, after the result, on stderr. Never in CI, non-interactive mode, or --json. Tips, update notices, and optional offers share this gate.
  • One line starting Tip:, which may be faint, then the command on its own line if there is one. A tip never delays, prompts, or changes the exit code, and respects VERCEL_GUIDANCE_DISABLED.
  • Anything that needs attention every time is a warning, not a tip.

Machine results

--json is the machine interface, and a contract. Every command that reads or changes a resource supports it. stdout then holds exactly one JSON document and a newline. stderr stays empty except for --debug output, CI ::add-mask:: lines, and, on failure, the error document. --follow switches that invocation to JSONL, and Logs and Traces Search write JSONL rather than one document.

  • Mirror the API, with camelCase keys, API enums and timestamps, and stable IDs.
  • Guaranteed fields are those in the command’s result schema. Other API fields pass through unchanged and can change with the API, except secret fields: the shared JSON writer drops any field the schema marks secret, unless the schema marks it as the command’s delivered value.
  • Key shapes by noun, so top-level fields can be added safely:
OperationShape
Read one{ "project": { … } }
List`{ "projects": [ … ], "pagination": { "next": "<cursor>"
Mutation`{ "project": { … }, "outcome": "<verb, past tense>"
Bulk{ "results": [ { "id": …, "outcome": …, "error"?: { … } } ], "summary": { "succeeded": 2, "failed": 1, "skipped": 0, "unknown": 0 } }
{
  "deployment": { "id": "dpl_example", "readyState": "BUILDING" },
  "outcome": "accepted",
  "next": [{
    "command": "vercel deployments inspect dpl_example --wait",
    "argv": ["vercel", "deployments", "inspect", "dpl_example", "--wait"]
  }]
}
  • Any result may add 2 shared top-level fields: warnings: [{ "reason", "message" }] and next: [{ "command", "argv", "when"? }]. when is the condition for using the command, or a note on filling its placeholders. After a mutation, next includes the resource’s inspect command, or its list command after delete or revoke, or when there is no inspect. JSON next ignores guidance settings.
  • Inside a document, an empty list is [] and a known-absent value is null, never omitted. Optional top-level fields (warnings, next, and an error’s userActionRequired, retryable, requestId, and retryAfter) appear only when they apply. A withheld secret field is omitted, never null.
  • Pretty-print a stdout document with 2-space indentation when stdout is a TTY, and write compact single-line JSON otherwise. An error document on stderr is always one line. Consumers never depend on whitespace or key order.
  • Commands with a result schema accept --fields <FIELDS>; an unknown field lists the valid ones.

Machine errors

With --json, a failure writes nothing to stdout and exactly one single-line JSON error document to stderr (pretty-printed here). stderr carries nothing else except --debug output and ::add-mask:: lines: no progress, receipts, notices, or hints. Bulk operations and JSONL streams differ: a bulk operation writes its partial result to stdout and no error document, and a JSONL stream keeps the lines it already emitted. In every case, the exit code is the source of truth.

{
  "status": "action_required",
  "reason": "missing_scope",
  "message": "Can't link without a team in non-interactive mode. 3 teams are available.",
  "next": [{
    "command": "vercel link --scope <TEAM>",
    "argv": ["vercel", "link", "--scope", "<TEAM>"],
    "when": "Replace <TEAM> with a team slug from data.teams"
  }],
  "data": {
    "teams": [{ "slug": "acme" }, { "slug": "acme-labs" }, { "slug": "acme-oss" }]
  }
}
FieldRule
statusaction_required when the command is blocked before any effect, and input, approval, or a human step would let it run; otherwise error, including failures a human must fix after an effect started
reasonA stable snake_case code from one shared registry of reasons
messageThe human headline without its glyph. Never parse it; its wording changes as copy improves, and reason doesn’t
nextRecovery commands, shaped like a result’s next
userActionRequiredtrue when a human must approve or perform a step (approval, browser consent, SSO)
dataResolved choices and context; issues ([{ "field", "reason", "message" }]) for validation; the idempotency key or operation ID for unknown_outcome when one exists. API and partner messages, and remote values that fail their selector’s identifier grammar, go here, never in message or next
requestIdWhen the API provides one
retryabletrue only when repeating the command is safe: same target, no duplicated effect. An unknown outcome is false unless the rerun reuses a supported idempotency key, and next then gives that exact command
retryAfterSeconds to wait, when known. A delay, never permission: retrying still needs retryable: true
  • The class sets the exit code, never status: missing_scope exits 2 and login_required exits 1. canceled isn’t a class; it exits 130 or 128 + n.
  • The error document carries warnings too, and is always the last line of stderr.
  • With --json, a cancel or signal writes one error document with reason: "canceled" and the remote state in data.remote. Observational follow modes write nothing.
  • For destructive and severe operations, confirmation_required sets userActionRequired: true and puts the preview in data.effects. Its next entry reads when: "Only after a human approves: <consequence>". An agent must not add --yes, or a --force that replaces user data, without that approval. For severe work, the continuation command names the resource by its stable ID and the team explicitly. The document may include data.effectsDigest; rerunning with --effects-digest <DIGEST> fails with effects_changed if the target or effects changed since the preview.
  • The reason codes in this manual are these JSON values. In human mode, the same conditions print as human errors.

Streams & other protocols

  • JSONL streams write one complete JSON object per line, flushed as each event arrives, with a stable type when a stream carries more than one kind of event (log, warning, summary). Never buffer a stream into one JSON array.
  • A successful bounded (non-follow) query ends with one summary line: { "type": "summary", "recordsReturned", "timeRange", "pagination": { "hasMore", "next" }, "excludedIntervals" }. hasMore says whether more records matched, and next is the cursor for --next, or null. Moving an existing stream to this shape is a contract change.
  • A stream error ends the stream with one JSON error document on stderr.
  • Logs and Traces Search write JSONL with --json, and also in any non-interactive run, CI and detected agents included, a long-standing behavior they keep. No other command infers a machine format from the mode.
  • Each streaming command documents snapshot versus follow, ordering, time window, reconnect and gap behavior, and when it stops.
  • Following a collection (env list --follow) prints the current list, then one activity row per change. With --json, the first line is { "type": "snapshot", "<nouns>": [ … ] }, and each change is a line with type added, updated, or removed. A polling follow mode states its interval in help and honors Retry-After.
ProtocolRule
Raw API bodyvercel api prints the response body exactly; --include adds the status line and headers
File or bytesExact bytes to the --output destination or a non-TTY stdout. A TTY gets escaped output unless --output -. Status goes to stderr
Child processThe child owns stdout, stderr, and the exit code; the CLI never wraps them
Plain valueA command that prints one value (a URL, a requested token) prints it alone, with a newline

Failure & recovery

Design errors as recovery

An error tells a person or an agent what failed, why, and exactly what to do next. It never guesses a cause, blames the user, hides partial work, or reports a failed read as empty.

✗ <Headline: what failed, then the known cause.>
  <Detail or issue rows>
  <Context rows>
  <ID rows>

  <Recovery instruction>:
    <command>
PartRule
HeadlineThe failed action and its exact object, then the known cause, in 100 characters or fewer when possible: Couldn't find project acme-wbe in acme.
DetailWhat the headline can’t hold: each validation issue, a code frame, the API’s own attributed message
ContextFacts needed to act or report: an inferred Team or Project, File, Limit, Docs
IDsNormal-foreground rows labeled per the ID labels, last so they’re easy to copy. Resource IDs needed for recovery always show; Request IDs only on Platform, Network, and Unknown outcome errors
RecoveryAfter a blank line, an instruction ending in : and the command (or a URL) indented 4 spaces. At most 2 options, likeliest first, or a plain sentence when no command applies. Never “try again” alone: give the command to rerun, or the status command when the outcome is unknown
  • Omit parts with nothing true to say. Outside issue lists and code frames, an error should fit in 8 lines; when trimming, keep required context, consequences, IDs, and recovery.
  • A blank line separates the error from earlier output; continuation lines indent 2 spaces.
  • Never put a status code in the headline, or show a raw API payload or a stack trace outside --debug.
✗ Can't confirm whether the deployment finished. The connection closed while waiting.
  Deployment ID   dpl_9x1Kq2

  Check its status:
    vercel deployments inspect dpl_9x1Kq2

Classify the failure

Every failure has exactly one class. The class fixes the headline formula, the allowed reason codes, and the exit code.

ClassHeadline formulaExample reasonExit
UsageUnknown option --x for vercel <cmd>. / Can't use --a with --b. / Can't <verb> <object>. <n> <inputs> are invalid. / Unknown command <segment> for vercel <path>.invalid_arguments, unknown_option, unknown_command2
Missing inputCan't <verb> without <thing> in non-interactive mode.missing_scope, confirmation_required2
AuthenticationYou're not logged in. / Your login expired.login_required, token_expired1
PermissionOnly team <role>s can <verb> <object>. Ask a team <role>. / As a <role> on <team>, you can't <verb> <object>. A <role> role is required. / This token can't <verb> <object>.permission_denied, token_scope_required1
Not foundCouldn't find <noun> <name> in <team>.not_found, project_not_found1
ConflictCan't <verb> <object>. <Conflicting state>.conflict, stale_version1
Limit or planCan't <verb> <object>. <Team> has reached <limit>. / Upgrade to Pro to <verb> <object>. / Monthly <limit> reached. <What is paused>.plan_limit, policy_denied1
Rate limitToo many requests to the Vercel API. Try again in <time>.rate_limited1
NetworkCouldn't reach <host>. <Cause>.network_error1
PlatformFailed to <verb> <object>. <Cause>. / Build failed.api_error, build_failed1
Unknown outcomeCan't confirm whether <operation> finished. <Cause>.unknown_outcome1
Partial<Verbed> <n> of <total> <nouns>. <m> failed., adding <k> unknown. when outcomes are unknown; unknown items never count as failed. When every item fails in one class, use that classpartial_failure1
VerificationCouldn't verify <URL>. <Known cause>. The deployment may still be ready; the command reports that state separatelyverification_failed1
Config<file>:<line>:<col> <problem>. / <file>: <key path> <problem>.invalid_config1
CLI bugUnexpected error in vercel <cmd>. This is a bug in Vercel CLI.internal_error1

The other reason codes in this manual:

ClassCodes
Missing inputambiguous_project, missing_project, env_key_sensitive, not_linked, missing_name, missing_value, missing_environment, missing_timeout, terms_required (with userActionRequired: true and data.url)
Usageinvalid_environment, branch_requires_preview_only, missing_command, agent_cannot_switch
Authenticationsso_required
Permissionscope_not_accessible
Conflictowned_by_another_team, env_file_exists, price_changed, port_in_use, stale_link, effects_changed
Platformcli_outdated, spawn_failed
Unknown outcometimeout, for any wait that reached --timeout
Canceled (exit 130, or 128 + n for a signal; not a class)canceled, in JSON only
  • Verbs: Can't for a present blocker, Couldn't for an attempt that failed, Failed to for a system or build failure.
  • Permission: name the blocked action and object, and route to whoever can resolve it. When the API returns the user’s role and a recommended role, say both: As a viewer on acme, you can't update example.com. A developer role is required. Never infer a role from a list of roles.
  • Plan: route to the upgrade. Enterprise-only features route to sales.
  • Owned by another team: a publicly identifiable resource (a domain) owned elsewhere is a Conflict (owned_by_another_team), not a permission error, because the user’s own team owners can’t resolve it. The error says so, then offers a different domain or a transfer from the owning team: Can't add example.com to acme-web. Another team owns it.
  • Third-party auth: name the provider and the cause: Your GitHub connection expired. (reconnect), GitHub uninstalled the Vercel app. (reinstall), The repository was deleted on GitHub. (connect another).
  • Not found: stay inside the caller’s team, and never reveal that a private resource exists elsewhere. Suggest one unambiguous match in that team (Did you mean acme-web?) and never act on it. In JSON, the suggestion goes in data.suggestion, never in next or a runnable destructive command.
  • Limit: state the verified limit and the supported remedies, never a guess.
  • Rate limit: shown once the retry budget runs out, or on the first 429 for a mutation that can’t be retried automatically.
  • Network: name the host; honor HTTPS_PROXY, NO_PROXY, and NODE_EXTRA_CA_CERTS; never fall back to cached remote state.
  • Unknown outcome: say what might still be happening, and recover by inspecting, never by retrying.
  • Canceled: a user cancel isn’t an error. Print Canceled., with no glyph, only when the remote operation never started; otherwise lead with Stopped waiting. and the confirmed facts. Then say what changed: Nothing was changed. or Uploaded files were discarded. No deployment was created. Observational follow modes and dev servers stop silently instead. A successful cancel command is an ordinary result: ✓ Canceled, exit 0.

Map API errors

  • Translate the HTTP status and the API’s error code into a class, a stable reason, and CLI-written copy, in one shared place, never per command.
  • API and partner messages never appear in the headline, message, or next. The CLI can’t vouch for text it didn’t write, and an agent might act on whatever appears in next. They appear only in an attributed Detail row (Neon: This database has been suspended for review.) or in JSON data.remoteMessage, stripped per the remote text rules.
  • A remote name (a project, a domain) appears in a headline or message only if it matches its selector’s identifier grammar. An API message about a request that carried a secret is never shown; map it to CLI copy.
  • Unmapped codes become Platform errors (api_error) with the HTTP status as detail and the Request ID from the x-vercel-id header.
  • A 5xx or timeout on a mutation that isn’t idempotent (documented or keyed) is an Unknown outcome, unless the endpoint guarantees the change wasn’t applied. A 503 or a Retry-After header is no such guarantee: Retry-After says how long to wait, never that a mutation is safe to send again. A 429 is such a guarantee: the API rejected the request without acting on it, so it’s a Rate limit error with retryable: true and retryAfter, never retried automatically for a mutation that isn’t idempotent.
  • Marketplace partners’ actionable errors keep the partner’s exact words in the same attributed Detail row, because users need them to get support.
  • Other upstream providers (payments, Git, AI models) are translated, with a Provider Error row holding a short code (card_declined) when it helps triage.

Validate before work

Validate all local input before the first request, and report every problem at once. One run then surfaces every fix, and an invalid item can’t stop a change partway through. Human issue lists show at most 5; JSON carries them all.

✗ Can't import 12 DNS records. 2 records are invalid.
  zone.txt:4      TTL must be a number.
  zone.txt:9      MX records need a priority.

  Nothing was imported. Fix zone.txt, then run:
    vercel dns import example.com zone.txt

Config errors point to the exact location and show the surrounding source. Schema errors name the key path and the accepted values: ✗ vercel.json: "regions" must be an array of region IDs, like ["iad1"].

✗ vercel.json:14:5 isn't valid JSON. Expected "," or "}".
  12 │   "rewrites": [
  13 │     { "source": "/a", "destination": "/b" }
  14 │     { "source": "/c" }
     │     ^

Usage errors name the unknown or conflicting token, suggest at most one close alternative without running it, and point to help.

✗ Unknown option --prdo for vercel deploy. Did you mean --prod?

  See all options:
    vercel deploy --help

Error exemplars

✗ Your login expired.
  Team            acme

  Log in again:
    vercel login
✗ Can't create project acme-api. acme has reached the Hobby limit of 200 projects.

  Find projects to delete:
    vercel projects list
  Or upgrade to Pro for more projects:
    vercel billing buy pro
✗ Unexpected error in vercel env add. This is a bug in Vercel CLI.
  Error           TypeError in src/commands/env/add.ts
  Version         Vercel CLI 60.1.3, Node.js 22.9.0, darwin-arm64

  Review the `--debug` output, which includes team and project names, then report it:
    https://github.com/vercel/vercel/issues/new?template=bug_report.yml

A bug report link never includes argv values, paths, or tokens, and the Error row never includes text derived from input.

Warnings

A warning is a nonfatal condition that needs attention; routine information isn’t one.

  • A warning uses the ! gutter, states the consequence, and gives the fix: inline when it’s a short sentence (Use --json.), otherwise in the recovery layout.
  • Deprecations name the replacement and print at most once per run: ! --format json is deprecated. Use --json.
  • Human warnings go to stderr. With --json, they go in the document’s warnings array, or as type: "warning" lines in JSONL.
  • Never print both a warning and an error for the same condition.
  • Usage thresholds each include the command to raise the limit or upgrade:
    • At 80%: ! You've used 80% of your monthly <limit> (<current> of <max>). (usage_threshold)
    • At 100%, a blocked command fails as Limit or plan (plan_limit): Monthly <limit> reached. <What is paused>.
    • In billed overage: ! You've exceeded your monthly <limit>. Additional usage is billed at <rate>. (usage_overage)
ReasonCondition
deprecatedA deprecated command, option, or alias was used
usage_threshold80% of a monthly limit is used
usage_overageUsage is past the limit and being billed
stream_gapA follow mode reconnected and might have missed events
link_team_mismatchThe directory’s link uses a different team than the current team
link_trackedGit tracks the .vercel/ directory
link_pin_mismatchAn environment pin disagrees with the directory’s link
insecure_versionThe activated CLI version is below the minimum secure version
limit_clamped--limit exceeded the command’s cap and was clamped
env_file_trackedGit tracks, or doesn’t ignore, an env file the CLI wrote
env_var_skippedA loader or CLI-control variable was withheld from a child process
port_fallbackThe default port was taken, so the next free one was used
secret_not_returnedA Secret’s value wasn’t returned and was left unfilled

Retries & unknown outcomes

  • Every finite operation has request timeouts, a retry budget, and a limit on total waiting, including polls that keep returning a non-terminal state.
  • Retry only transient failures, with backoff, honoring Retry-After. Reads (GET, HEAD) retry automatically.
  • Retry a mutation only when replaying it is safe: the endpoint documents idempotency, or the API supports an idempotency key and the request reuses it, with the same payload, on every attempt. Otherwise a 5xx or a network failure after sending is an unknown outcome, because the server might already have applied the change; inspect before repeating.
  • In human mode, print Retrying automatically… while retrying. When the budget runs out, the error keeps its class’s headline and adds a Retries detail row with the count.
  • Never answer an unknown outcome with a blind retry. Keep the operation’s identity and a status command.

Partial & staged work

  • Bulk operations report what succeeded, failed, was skipped, or is unknown; whether the operation is atomic; and which subset is safe to retry. A partial result exits 1.
✗ Removed 3 of 5 DNS records. 1 failed. 1 unknown.
  rec_8aj2        Record not found.
  rec_91kd        The request timed out.

  Check whether the timed-out record was removed:
    vercel dns inspect rec_91kd
  • update distinguishes omitted (unchanged), explicitly empty (cleared), and new values. Read-modify-write uses version or ETag conditions; a conflict means re-read, never a blind retry.
  • Staged changes report ✓ Staged <noun> <name> with a Version row, then the diff, publish, and discard commands (outcome: "staged", plus version).
  • diff prints one change per row, prefixed +, -, or ~, and exits 0 whether or not anything differs. --exit-code makes it exit 1 when something does, for CI drift checks; that’s a result, not an error, so the diff stays on stdout and no error document is written. --json returns { "changes": [{ "id", "change": "added" | "removed" | "updated", "before", "after" }], "version" }.
  • publish previews every staged change with who made it, and publishes only the version it previewed; a newer one is a stale_version conflict. It’s destructive when it blocks or challenges traffic. Never publish unrelated staged work as a side effect.
  • Server-side schedules (a progressive rollout) report the start, ✓ Started and outcome: "started", never their final state.
  • Moves that take something from another resource (an alias or domain from another project) show a Previous row and return previous<Noun> in JSON.
  • --dry-run does the reads and validation, performs no mutation, and says what would change. It never prompts and needs no --yes, still validates a given --amount (price_changed), and on a staging command previews the stage without staging. In JSON: outcome: "planned", with the changes array from diff.
  • Make no-ops explicit: example.com is already assigned to acme-web. (exit 0, outcome: "unchanged").

Long-running work & cancellation

  • Respond within 100 ms of starting slow work. A spinner names its phase (Uploading files…); a progress bar needs a real total; percentages are never invented.
  • Animate only with rich presentation in interactive mode. Otherwise, print each phase change once as a plain line, and for byte transfers a line at each further 10%, or after 30 seconds without one, whichever comes first, at most once every 10 seconds: Uploading big.mp4… 800 MB of 2.0 GB (40%). Progress clears before results, prompts, and errors, never spins over logs or child output, and parallel work shares one indicator.
  • Past its usual duration, work says so once: Still <verb>ing. Most <operations> finish within <duration>. When it’s waiting on something external, name it: Waiting on DNS propagation. This can take up to 48 hours. Never This might take a while. A resource ID or status link may appear as soon as it exists, so people can follow the work; a Request ID appears only on failure.
  • Waiting commands support --timeout and state its default.
  • --no-wait returns once work is accepted, reports it as accepted, and gives the ID and status command; it never claims completion. Inspect commands for async resources support --wait (with --timeout) to block until a terminal state. A compound operation reports only the phases that completed.
  • --wait exits as the originating command would: a failed build is build_failed, exit 1. A wait that reaches --timeout before a terminal state exits 1 with reason: "timeout" and the status command. --timeout with --no-wait is a usage error.
  • Follow modes (--follow, dev servers) run until stopped and never buffer an unbounded stream. After a disconnect they print ! Lost connection. Retrying automatically… once, and reconnect with backoff capped at 30 seconds. After reconnecting, they warn once about the gap (stream_gap), with a command for the missing window. After 5 minutes without reconnecting, they end with a Network error. With --json, the reconnect notice is omitted and the stream_gap warning is still emitted.
  • An observational --follow (one that only watches, such as a log stream) accepts --timeout, and reaching it exits 0, because observing for that long was the task. A follow that waits on work it started follows the --wait timeout rule above. In CI, --follow without --timeout fails as Missing input (missing_timeout).
  • The first Ctrl+C stops local work and restores the terminal; a second exits immediately. SIGTERM and SIGHUP get the same bounded cleanup.
  • After a cancel, a timeout, or an unknown outcome, report only what’s confirmed about the remote work: it never started (No deployment was created.); it exists, with its ID, last confirmed state, and whether it may continue (Deployment dpl_9x1Kq2 continues building. Check it with: and the command); or its creation is unknown (Can't confirm whether a deployment was created.). JSON errors carry this as data.remote: none, finished, may_continue, or unknown. Recover by inspecting the known ID, or by listing when there isn’t one, never by resubmitting. Never claim remote work was canceled because local waiting stopped.

Exit codes

CodeMeaning
0The promised operation completed: success, an empty result, a no-op, acceptance under --no-wait, help, or version
1Operational failure, as set by the error class; also diff --exit-code finding changes
2Usage error or missing input, as set by the error class
130Canceled by the user: Ctrl+C (SIGINT), Escape, or declining a confirmation the operation needs
128 + nTerminated by signal n (SIGTERM exits 143, SIGHUP exits 129), whether the CLI or its child received it
Child codeA command that runs a child (env run, extensions) exits with the child’s code when the child exits on its own
  • Never exit 0 after a failure because output was printed.
  • Declining an offer after the result keeps the result’s exit code and prints no Canceled.
  • A closed stdout (| head) ends a read or stream quietly: exit 0, no error output. A mutation already sent finishes and exits with its real outcome.
  • Post-command work (update checks, telemetry) never changes the exit code.

Pagination & coverage

  • --limit is the total number of results wanted. The CLI pages internally to reach it and never fetches more than it needs. Every list supports --limit, and --next when more results can exist.
  • A value above the documented cap is clamped, with a limit_clamped warning, so a script keeps working when the cap changes. A non-integer or a value below 1 is a usage error. Help documents the default order, default limit, cap, and which filters run on the server.
  • When more results exist, return pagination.next in JSON and a Next page: command in human output. next is an opaque, CLI-owned string or null, never the API’s pagination object.
  • Filters, order, team, project, and time window stay fixed across pages. A cursor is bound to them: an omitted filter inherits the cursor’s, and a conflicting one is a usage error.
  • Fetching every page takes --all, and is bounded and cancelable. If a later page fails, human output reports how many rows were printed and a cursor after the last one. A JSON list writes nothing to stdout; its error carries data.rowsFetched and the cursor the run started from (null for the first page), because no rows reached stdout. Never present an incomplete collection as complete.

Compatibility & quality

Files, stdin & sensitive data

  • Declare every input and output as text, JSON, or bytes, with its encoding, size limits, and newline handling. Never decode bytes as UTF-8.
  • - means stdin or stdout where the capability is file-shaped. Only one input may read stdin; competing sources are a usage error. A text value read from stdin drops exactly one trailing \n or \r\n.
  • Paths resolve against --cwd. Overwriting a file the CLI didn’t create is destructive unless the file is named in argv and --force is given. Commands that update files say what they preserve.
  • Every write, config and state included, goes to a randomly named temporary file created exclusively in the target directory, then is renamed into place. An interrupted write never leaves a truncated file behind. Refuse to write under --cwd through a symlink that resolves outside it.
  • A remote filename never contains a path separator; a remote pathname never contains .. or an absolute prefix; the resolved path always stays under its destination.
  • Files that hold secrets (env pull output, .vercel/ state) are created owner-only (0600). env pull warns env_file_tracked when Git tracks the destination or doesn’t ignore it.
  • Never alter shell profiles or system config, or install tools, as a side effect of an unrelated command.

Secrets are tokens (including VERCEL_OIDC_TOKEN), environment variable values of either type, protection bypass secrets, Deploy Hook URLs, signed and presigned URLs, SDK Keys, webhook signing secrets, and connection strings.

  • Secrets never appear in suggestions, diagnostics, debug output, telemetry, receipts, errors, or pass-through JSON, and are never echoed after entry, even when invalid. Result schemas mark secret fields; the shared JSON writer drops them unless the schema marks one as the command’s delivered value.
  • Prefer stdin or a masked prompt over argv for secret input. Arguments appear in process lists and shell history.
  • A secret read from - fails as a usage error (invalid_arguments) when stdin is a terminal, before reading, and says how to pipe it or use the masked prompt.
  • Requested delivery is the exception. env pull, one-time token creation, API responses, logs, and env run deliver sensitive data through their documented channel and never repeat it elsewhere.

Remote text (names, log lines, commit messages, API and partner messages) is data, never instructions. A crafted name can rewrite the terminal or impersonate CLI output, so in human output, strip C0 and C1 controls, escape sequences, and bidirectional and zero-width format characters. Show newlines in single-line fields, and tabs in non-TTY table cells, as visible escapes. Raw or byte output to a TTY escapes non-printable bytes unless --output - is given.

Child processes & local servers

  • A wrapper prepares; the child owns its argv, streams, and exit code. Vercel options end at the documented handoff, usually --. Child arguments pass as an argv array, never a joined shell string.
  • Child stdout and stderr are inherited, never wrapped in JSON. Wrapper failures happen before the child starts: a missing child command fails with missing_command (exit 2), and a child that can’t start fails with spawn_failed (exit 1). With --json, only those use JSON errors.
  • The CLI exits with the child’s code when the child exits on its own, and with 130 or 128 + n after an interrupt.
  • Document which source wins when Vercel, env files, and the parent shell set the same variable, and the child’s working directory. Values from Vercel or env files (env run, dev) never set loader or CLI-control variables (NODE_OPTIONS, LD_*, DYLD_*, PATH, BASH_ENV, PYTHONPATH, VERCEL_TOKEN, VERCEL_ORG_ID, VERCEL_PROJECT_ID) unless named with --allow-env <NAME>. A remote value that sets NODE_OPTIONS or PATH can run code on the developer’s machine. Each skipped variable warns once (env_var_skipped), without its value.
  • Forward signals and stop owned processes with bounded waits. Never leave an orphaned server.
  • Dev servers print Ready on <URL> on stderr once, before child output; a started server is not a finished build. A taken explicit port is a conflict (port_in_use) with the recovery vercel dev --listen <PORT>. A taken default port moves to the next free one, with one warning: ! Port 3000 is in use. Using 3001. (port_fallback).

Configuration files

  • The CLI edits vercel.json only on explicit request, preserving formatting and unrelated keys. It never edits vercel.ts; it prints the change instead.
  • .vercel/ holds CLI state: the link, env pulls, build output. Receipts mention it only when the user must act on it.
  • The CLI config directory holds auth and preferences, with owner-only credential files. Concurrent CLI processes never lose each other’s unrelated keys.

Updates & version skew

  • Update notices pass the tip gate, print at most once a day, never appear with NO_UPDATE_NOTIFIER, and take no glyph: Vercel CLI 61.0.0 is available. You have 60.1.3., then Upgrade: and vercel cli upgrade.
  • An upgrade offer is one question after the command finishes. Automatic updates are opt-in, and each is reported once.
  • vercel cli upgrade detects the install method (npm, pnpm, Yarn, Bun, Homebrew, standalone binary) and uses or prints the matching command, never overwriting a package-manager install another way. It runs package managers from the home directory against the official registry, and verifies standalone binaries against a signed checksum before replacing them.
  • cli versions activate warns insecure_version below the minimum secure version.
  • When the API rejects the CLI’s version, fail with cli_outdated, the minimum version, and the upgrade command.
  • Unknown API enum values render raw and never crash.
  • Auth, config, and caches stay readable by older and newer versions; a format change ships with a migration.

CI, telemetry & performance

  • CI output stays human unless --json is selected, because people read CI logs. Logs and Traces Search keep their documented JSONL. Human mode may emit GitHub Actions annotations (::error file=…,line=…::) on stderr for config errors, but never workflow commands that change CI state (::add-mask::, environment files) unless an option asks for them. The exception: in GitHub Actions, a command delivering a requested secret first emits ::add-mask:: for it on stderr, in every format, --json included.
  • Disclose telemetry on the first run: a short notice interactively, or one stderr line in CI and non-interactive human mode, never a prompt. With --json, the disclosure waits for the next run without it. Nothing is sent before the disclosure. Opt out with vercel cli telemetry disable or VERCEL_TELEMETRY_DISABLED=1.
  • Telemetry records command paths, option names, failure reason codes, and exit codes, so the team sees which failures people hit. It never records values, secrets, file contents, paths, or remote data. Unknown path segments are recorded as <path> or <extension>. It never slows a command or changes its output.
  • Help, version, and local commands start without network access, loading command modules lazily. Help and version should render within 200 ms on a warm cache, with startup time tracked in CI so regressions show. Independent requests run in parallel. Non-essential work (update checks, telemetry) never blocks the command.

Change contracts deliberately

The contract is everything a script can depend on: command names, option names and meanings, defaults, prompts, output streams, JSON shapes, exit codes, environment variables, config files, non-TTY table headers and column order, and a mutation’s bare stdout identifier. Change it only as this table allows, and never break a script silently.

ChangeRequirement
Human copy, layout, or help text outside the contractUpdated tests; no migration
Add a command, option, JSON field, or aliasTests for the new behavior and for unchanged old invocations
Rename a command or optionThe old name stays as a deprecated alias (warning reason deprecated) for at least one major version; ships in a minor release
Change a meaning, default, type, stream, exit code, or JSON shape; remove anythingA major version, release notes naming the replacement, and a deprecation period first where feasible
  • An alias bridges a rename, never 2 meanings. Changing what a token means requires removing it first, so an old script fails loudly instead of silently doing something new.
  • A breaking stream or format change may ship a compatibility switch (VERCEL_COMPAT_<NAME>=1) that restores the old behavior for one major version.
  • Use telemetry to measure a deprecated input’s usage, without collecting values.
  • Add exit code, stream, and JSON assertions for the new contract.

Verify public behavior

A snapshot, a metadata entry, or a polished transcript doesn’t prove a command works. Test public behavior at the narrowest boundary that exercises it, with no live mutations.

ChangedEvidence
Names, parsingLong and short forms behave identically; aliases; unknown, repeated, and conflicting options; globals at nested depth; -- handoff
HelpEvery entry point reaches the same help; unknown paths fail; help works offline before auth; section order; examples parse without being run
Context, inputExact resolution; the explicit target wins; typos never create or fall back; malformed config fails; one stdin owner
OutputJSON parses from stdout, and error JSON from stderr; each stream asserted; empty versus missing versus partial; no ANSI in JSON
Collections--limit is a total across pages with no over-fetch, clamped with limit_clamped above the cap; ordering; first, next, and last page; filters fixed across pages
MutationsNothing written before validation and consent; exact target; default No; --yes versus --force; no duplicate on retry; partial report
Long-runningBounded waits, including endless pending; cancellation exits 130; claimed phases happened; accepted versus ready
Files, secretsEncoding and bytes; overwrite refusal; atomic writes; no secret in incidental output; requested delivery still works
Processesargv with spaces and metacharacters; a child’s exit 42 passes through; spawn failure; signals; no orphans; a quiet closed pipe
PresentationBefore-and-after transcripts at 40, 80, and 120 columns; long and Unicode values; rich and plain presentation; each stream on its own; gutter and receipt
ContractsOld inputs, JSON shapes, streams, and exit codes, unless the change is an intentional contract change
  • For changes to prompts, streams, format, consent, or progress, test every mode; copy-only changes are exempt. Test success and failure on an interactive TTY, with stdout redirected, with stdin piped, with --json on a TTY, with --non-interactive on a TTY, in CI with a TTY, and as a detected agent. Assert whether a prompt appeared, what each stream holds, and the exit code.
  • Check rich and plain presentation on purpose. Run the styled check with NO_COLOR and FORCE_COLOR cleared, because a shell that sets NO_COLOR hides every styling failure. Then check --no-color, TERM=dumb, and redirected output, with stdout and stderr captured separately. Stripping the styling must recover the exact text, commands and quotes included. JSON, identifiers, and secrets stay unstyled even when color is forced.
  • For new commands and flows, you should also walk and read the transcript of each journey the change touches: first run with no login; an expired token or SSO mid-command; several teams; a monorepo; a GitHub Actions deploy; an agent’s discover, act, verify, recover loop; offline; rate limited; a long deploy interrupted; partial bulk failure; a destructive Production change; a broken config file; a CLI older than the API expects; Windows PowerShell; accessible mode; piping into jq, grep, and head; two CLI processes at once.
  • Parser, help, and global option changes affect every command; link and input helpers affect every setup caller; output helpers affect every adopter. Trace call sites, test the helper, and test at least one materially different caller.
  • Keep exact column tests at the shared layout helper. For wording, assert the meaningful new outcome, and reject stale strings where regressions are plausible.

Enforce the rules in shared code

Rules that depend on every call site erode. Enforce the high-risk ones in shared code rather than in review:

RuleMechanism
Mode detection in one placeOne resolved mode on the client; a lint banning isTTY and process.env.CI outside the shared module
No prompts in non-interactive modeA prompt helper that throws a typed missing-input error, which the top level maps to status: "action_required" and its Missing input reason
Streams and JSON purityOne result writer for compact or pretty JSON, secret fields, and warnings; a JSON mode that turns human lines into no-ops; a test helper asserting one stdout document and a clean stderr
Help contractCentral help dispatch right after the first parse, before config, auth, and team resolution
Color and glyphsOne theme module, and a lint restricting color-library imports to it
Consent tiersA consequence in command metadata, and one confirmation helper that renders the preview and produces confirmation_required
Error classes and reasonsA typed error carrying class, reason, data, and next; one API-error mapper; reasons typed from one registry
Mutation retriesA fetch client that retries only GET, HEAD, and requests marked idempotent (documented or keyed)
SignalsOne root abort signal wired to SIGINT, SIGTERM, and SIGHUP, passed to every request and child process
FormattingShared formatters for ages, durations, counts, sizes, and money, used by every command
NamesA lint against the Reference tables, and a committed surface snapshot

Review the consequence

  • Reject a change that breaks a requirement, citing the concrete user consequence and the fix. Don’t reject on taste or demand unrelated refactors. An existing inconsistency never excuses a new one.
  • Also reject partial changes: prompt or result copy edited without checking the surrounding flow; one command path updated while parallel paths sharing its helper or contract are missed; behavior changed without tests that lock in the new and reject the old.
  • Review the real before-and-after output for order, rhythm, repetition, and the next action.
  • Record exceptions with the rule, the reason, the user impact, and the test. A rule that keeps needing exceptions gets revised.

Reference

Nouns

Use these terms in help, prompts, output, and errors. They set human meaning; JSON keys and values still mirror the API. “Identity” lists the forms a selector accepts, and a mutation prints the first as its stdout identifier. “Never say” lists synonyms banned from copy, option names, and positional names.

  • Spelling and casing match the dashboard’s glossary, so a term reads the same in the dashboard, docs, and CLI. When they disagree, align them; never fork.
  • Terms are Title Case in aligned labels, table headers, and help section titles (Environment Variable), and lowercase in sentences (environment variable), except for preserved-case names.
  • Preserved case, Title Case even in prose: Vercel, Vercel CLI (then “the CLI”), Production, Preview, Development, API Key, SDK Key, Rolling Releases, Global Config, Vercel Blob (then “Blob”), Vercel Sandbox, Vercel Firewall, Vercel WAF, Attack Challenge Mode, IP Blocking, Deployment Protection, Skew Protection, Vercel Queues, Fluid Compute, Observability, Web Analytics, Speed Insights, Spend Management, Hobby, Pro, Enterprise, AI Gateway, Vercel Agent, Vercel Toolbar, Instant Rollback, Deployment Checks, Deploy Hook, Marketplace, Observability Plus, Speed Insights Plus, Vercel Connect, Vercel Container Registry, Vercel Token Pass, and the environment variable types Config and Secret. Role names are lowercase in prose (team owners, a viewer).
  • Command tokens may shorten a noun (routes, certs, env, vcr); prose always uses the full noun (“routing rule”, “SSL certificate”, “environment variable”).

Account & context

TermMeaningIdentityNever say
TeamOwnership and access context for shared resources, selected with --scopeslug or IDorganization (for a team), org, workspace, account; “scope” in prose
UserA person with a Vercel loginusernameaccount (for a person), member (outside team context)
MemberA user’s membership in a team, with a roleusername or emailuser (when the role matters)
RoleA member’s access level: owner, admin, developer, viewer, member, and other team rolesrole nameadministrator, manager, read-only, observer
TokenA credential that authenticates the CLI and APIID or name (never the value)key, secret, password; API Key (for tokens broadly)
ContextResolved user, team, project, and local settings for one invocationnonescope
OrganizationA group of teams managed and billed together through its root team (vercel organizations)slug or IDorg, enterprise, workspace, account
Child teamA team in an organization, billed through the organization’s root teamslug or IDsub-team, subteam, member team

Projects & deployments

TermMeaningIdentityNever say
ProjectPersistent resource holding settings, domains, and deploymentsname or IDapp, site, repo, repository
DeploymentOne deploy result with its own ID, URL, and lifecycleURL (stdout) or IDbuild, release, dpl; “deploy” as a noun
BuildWork that produces deployment artifactsIDdeployment, compile
EnvironmentProduction, Preview, Development, or a custom environmentslugtarget, stage; prod, live, dev, local (in prose)
Custom environmentA named project environment, managed with vercel environmentsslug or IDtarget (in prose), stage
Environment VariableNamed configuration value scoped to environments and optionally a branchnameenv var, EnvVar; “secret” for any variable that isn’t the Secret type
Config / SecretThe 2 environment variable typesnonesensitive, plain, encrypted
LinkAssociation between a local directory and a projectdirectoryconnection
Root DirectoryProject setting for where source lives in the repositorypathproject path
Git repositoryThe repository a project is connected torepository URLrepo (in labels), git repo
Deploy HookA URL that triggers a deployment from a Git branchIDdeployment hook, webhook
Rolling ReleasesStaged traffic rollout between deploymentsprojectcanary release, gradual rollout
Instant RollbackReturning Production to a previous deployment. Verb “roll back”; noun “rollback”projectrevert, roll-back
Deployment ChecksChecks that must pass before a deployment is promotedname or IDtest, gate, precheck
ServiceOne part of a multi-service project, configured in vercel.json#servicesnameapp, microservice
DaemonA long-running container in a project, configured in vercel.json#daemonsnameworker, background service
Daemon instanceOne running copy of a daemon in a regionID (dmni_…)replica, pod

Domains & routing

TermMeaningIdentityNever say
DomainA registered or external domain and its ownership and configurationdomain namesite, URL
Apex domainA domain without a subdomain (example.com)domain namenaked domain, root domain, bare domain
RegistrantThe person or company a domain is registered to, its legal ownernoneowner (for the registration), WHOIS contact
AliasA hostname assigned to a deploymenthostnamedomain (for the assignment); say “command alias” for alternate command names
DNS recordA typed DNS entry for a domainIDentry, alias
SSL certificateA certificate for a domain (vercel certs)IDTLS certificate, cert (in prose)
Bulk Redirects / redirectThe feature / one rule that sends a request to another URLsource pathredirect rule, route
Project Routing Rules / routing ruleThe feature / one request-routing rule (vercel routes)name or IDroute (in prose), redirect
Vercel Firewall / firewall ruleThe product / one custom Vercel WAF ruleIDthe firewall (on first reference), filter
IP Blocking / IP blockThe feature / one blocked IP address or rangeIP or IDban, blacklist, IP blocklist
Attack Challenge ModeFirewall mode that challenges all visitors (firewall attack-mode)noneattack mode, challenge mode
System bypassA firewall exception that skips system mitigationsIDallowlist entry

Data, storage & platform products

TermMeaningIdentityNever say
Vercel Blob / Blob store / blobThe product / the container / one stored objectstore ID / pathnamebucket, file (for the blob)
Global Config / store / itemThe product / a key-value config store / one keystore ID / keyEdge Config (retired name)
Storage resourceA store of any kind attached to projects (vercel storage)IDdatabase (unless it is one)
Integration / installation / resourceOffering / its installed connection / a provisioned instanceslug / ID / IDplugin, app, add-on
ConnectorA Vercel Connect connection to a third-party serviceIDintegration, app
Feature flagThe product resource under vercel flagsslugtoggle, feature toggle; “flag” for a CLI option
VariantOne value a feature flag can servenametreatment, version
Segment / entity / label / SDK KeyTargeting group / targeted kind / tag / client credentialslug / kind / name / IDaudience, cohort, subject, principal
TargetEntity value a feature flag always serves a fixed variant toentity.attribute=valueoverride, allowlist, individual target
ExperimentA flag-backed experiment with analysisslugtest, A/B
Vercel Sandbox / sandboxThe product / one sandbox instanceIDsession, container, VM, microVM
Vercel Queues / queue / messageThe product / a named queue / one message in itname / IDtopic (unless the API calls it one), job
Cron jobA scheduled invocation defined in project configpathscheduled task, job
ScheduleA managed schedule resource (vercel schedules)IDcron (for this resource)
WebhookAn endpoint that receives Vercel eventsIDhook, web hook, deploy hook
Microfrontends groupProjects composed into one applicationnamemicro-frontends, zone
KMS issuer / key / grantSigning identity / key version / project permissionIDcertificate, secret
Container repository / image / tagVercel Container Registry objectsname / digest / tagrepo
AI Gateway API Key / virtual modelGateway credential / model aliasID / slugtoken, gateway token
Vercel Token PassTeam credits for Token Pass models; API Keys opt in at creation with --token-passteamgateway token pass

Observability, billing & collaboration

TermMeaningIdentityNever say
Runtime Logs / Build LogsFunction and request logs / a build’s output logrequest IDfunction logs, build output
DrainA destination that receives forwarded logs, traces, Web Analytics, or Speed Insights data (vercel drains)IDlog drain (for drains broadly), forwarder, sink
TraceA distributed trace for one requesttrace IDspan (for the whole trace)
MetricA queryable observability measurementmetric IDstat
Activity eventAn audit event for a user or team, in the activity logIDlog, event log
AlertA triggered alert (vercel alerts)IDincident
MonitorThe rule that defines when an alert triggers and where its notifications go (vercel monitors; the API calls it an alert rule)IDalert rule, rule
Agent RunOne execution in Vercel Agent, with its own ID and stateIDsession, job
Agent skillA directory of instructions and references (SKILL.md) that a coding agent loads for a tasknameplugin, prompt, rule
Comment / threadOne Toolbar comment / a thread of comments on a pageIDnote, message
Spend Management / spend amountThe team feature that limits on-demand spend / the configured limit (a budget). AI Gateway calls its limit a “monthly spend limit”IDspend cap, quota
Budget alertA Spend Management threshold reached in a billing cycle (vercel billing budgets alerts); not an AlertIDalert (alone), notification, history
UsageMetered consumption and cost for a billing periodnonebill, stats
PlanHobby, Pro, or Enterpriseplan nametier (in prose), subscription (for the plan)
FeedbackBugs, friction, and feature requests sent to the Vercel teamnone
Incident / componentA disruption reported on the Vercel status page / one monitored part of the platform there (vercel health)IDoutage (for an incident); service (for a component)
Billing planAn integration’s pricing option, or how a child team is billed in an organization (platform or enterprise), selected with --billing-planslugplan, tier

To add a noun, confirm it’s a distinct concept in both the API model and the dashboard glossary, add a row with its meaning, identity, and banned synonyms, and use it everywhere at once.

IDs

Label an ID by what it identifies, matched to its prefix, and never label a prefixed ID Request ID. An ID without a row here is labeled <Noun> ID; add its prefix row in the same change.

LabelPrefixIdentifies
Deployment IDdpl_A deployment
Build IDbld_A build
Integration IDcfg_An integration installation
Organization IDorg_An organization
Key IDkey_An API Key; for KMS keys use KMS Key ID
Request IDnoneOne API or platform request (x-vercel-id)
Run IDnoneA workflow, cron, or agent run
Monitor IDar_A monitor
Drain IDdrn_A drain
Record IDrec_A DNS record
Trace IDnoneA trace
Generation IDnoneOne AI Gateway model generation
Daemon Instance IDdmni_A daemon instance
Project IDprj_A project
Team IDteam_A team

Verbs

In a group, a command’s last segment is a verb from these tables or a view leaf; top-level tools and workflows follow the command grammar. Each matches the dashboard’s verb for the same action. A new verb needs a row in the same change, and a reason no existing verb fits.

Reading & changing

VerbMeaningUse instead of
listRead a collectionls (alias), show, get (for many)
inspectRead one resource in detailget, show, describe, info, fetch, view
createMake a new standalone resource with its own lifecycle (project, team, token, webhook, store, flag)add, new, register
addPut an existing thing into a container (a domain onto a project), or add an entry to a resource’s configuration list (environment variable, DNS record, redirect, rule, label)create (for these), attach, install (except the install shortcut)
inviteAdd a person who isn’t a team member yet, by email or accountadd (for people)
updateChange the specified fields of an existing resource; omitted fields stay unchangededit, patch, modify, change, configure
setAssign a value to a named slot, creating or replacing it (aliases set, flags set)update (when it’s an upsert)
renameChange a resource’s name onlyupdate --name (both may exist)
enable / disableTurn a feature or resource on or off without deleting itturn-on, on/off
moveChange a resource’s position in an ordered list (firewall rules move)reorder
statusRead the current state of a singleton feature or operation that has no IDinspect (when there’s an ID)
checkRun checks and report each result (security check, cli versions check)verify (for checks)
searchFind items by query (domains search, traces search, help search)find, lookup

Verbs that end or remove something are under Choose verbs by consequence, with how to recover from each.

Lifecycle verbs

VerbMeaning
deploy, redeployCreate a deployment / rebuild a previous one
promote, rollbackPoint Production at a deployment / at a previous one (prose: “roll back”)
build, dev, runBuild locally / serve locally / run a command or job now
link, pullAssociate a directory with a project / fetch project state locally
connectAttach an existing resource or external system (git, storage, integration resources, connectors); undone by disconnect
publish, discard, restoreMake staged changes live / drop staged changes / return to a previous version
import, exportBring many records in from a file / write them out
upload, download, copy, pushTransfer bytes to or from Vercel / duplicate server-side / upload a container image (Docker convention)
archive, unarchiveRetire without deleting / bring back
pause, resumeSuspend and continue serving or processing
scaleOverride a resource’s instance counts without changing its configuration
restartStop a running instance and start it again from the same configuration
start, approve, abort, completeStart a rolling release / advance its current stage / stop it and return traffic / finish it
block, unblockAdd an IP block / remove one
purge, invalidateRemove cached content / mark it stale
buy, renew, verify, claim, transfer-inDomain and marketplace lifecycle; transfer-in starts moving a domain’s registration to Vercel
reply, resolve, reopenReply to a comment thread / mark it resolved / reopen it
openOpen a resource in the browser (dashboard, Toolbar)
captureRecord a new sample of live behavior (a trace)
activateMake one version the active one among several (KMS keys, CLI versions)
acceptAccept legal terms
issueHave Vercel issue a certificate or credential
diffCompare 2 versions, or staged changes with live
applyApply a batch of changes (from input or several options) in one operation
split, rolloutSet a flag’s weighted variant split / progressive rollout
prepareGenerate build-time artifacts (flag definition fallbacks)
switchChange the current team
requestAsk for access to a team (teams request)
login, logout, signup, whoami, setup, upgrade, initCLI session and setup (prose: “log in”, “log out”, “sign up”)
  • A read-only leaf that prints one derived view or value may be named for it rather than a verb: firewall overview, firewall bot-management, teams sso, metrics query, metrics schema, projects access-summary, integrations balance, integrations discover, integrations categories, integrations guide, activity types, flags override, flags evaluations, flags datafile, connectors discover, connectors categories, agent-runs trace, agent-runs projects, ai-gateway models endpoints, ai-gateway leaderboard *, monitors schema, domains price, billing usage, billing contract, cli versions installed, cli completion.
  • A leaf that issues a credential may also be named for what it returns (projects token, connectors token, blob presign, blob signed-token), but issuing is never a read: it follows the credential rules, and its value is a secret.
  • status may follow a lifecycle verb to read that operation’s state (deployments promote status, deployments rollback status). It behaves like inspect: no remote side effects, and --json support.
  • Workflow leaves name what the workflow applies to: setup mcp, setup gateway.

Selectors & value hints

Name an identity the same way everywhere. Positionals and value hints use the noun, never its type or API field name. The rules for selectors are in Resource identity.

IdentityOptionPositional / value hintNever
Team-S, --scope (global)<team> / <TEAM>--team, --org, --slug for a team
Project-p, --project<project> / <PROJECT><app>, <name>, projectId, NAME_OR_ID, PROJECT_ID
Deployment--deployment<deployment> / <DEPLOYMENT>--dpl, --deployment-id, `<url
Environment-e, --environment (prefer a comma-separated list; repetition remains supported for compatibility)<environment> / <ENVIRONMENT>--target, --stage, TARGET, `production
Git remote--remotenone / <NAME>A URL instead of an existing, case-sensitive local remote name
Git branch--git-branch<branch> / <BRANCH>--branch, --trigger-branch, -b
User--user<user> / <USER>--user-id, <USER_ID>
Domain--domain<domain> / <DOMAIN><hostname> for a domain
Store--store<store> / <STORE>--store-id, storeId
Installation--installation<installation> / <INSTALLATION>--installation-id
Version--<noun>-version<version> / <VERSION>bare --version (the CLI’s), --version-id
Request--request-id<request-id> / <REQUEST_ID>requestId
Any other resource--<noun><noun> / <NOUN>camelCase (ruleId, issuerId), -id suffixes, id alone when the noun is known, <name-or-id>

Allowed value hints: <NUMBER>, <TIME> (ISO 8601 or relative), <DURATION> (30s, 5m), <PATH>, <FILE>, <DIR>, <URL>, <KEY=VALUE>, <CURSOR>, <TEXT>, <USD>, <PERCENT>, <JSON>, <NAME>, <VALUE>, <TYPE>, <FIELDS>, <PORT>, <LABEL>, <DIM>, <DIGEST>. Never <String>, <N>, <COUNT>, <MS>, <Boolean>, or any hint not listed here or named for a noun.

Standard options

When a command supports a concept in this table, it uses that row’s option. An option for any other concept (--level, --expand) is named for its field or noun in kebab-case and needs no row. Never advertise an option before its behavior exists.

ConceptOptionRulesNever
Machine output--jsonThe only format selector. See Machine results.--format json, -F, -j, --output json
Consent-y, --yesSee Bind consent to consequences--confirm, -c
Replace or rerun--forceSee Bind consent to consequences--overwrite, --allow-overwrite, -f
Preview--dry-runOnly with a real preview that performs no mutation--plan, --preview
Variable injection--env <KEY=VALUE>, --build-env <KEY=VALUE>Repeatable runtime / build values. Never an environment selector.-e, -b
Time range-s, --since <TIME>, -u, --until <TIME>ISO 8601 or relative (1h, 7d); state the default window and timezone--from, --to, --start, --end, --date
Result size-n, --limit <NUMBER>Total results wanted; the CLI pages internally (Pagination & coverage)-l, --count, --top, --per-page; --limit for money
Continuation--next <CURSOR>Opaque cursor from the previous page--page, --cursor, -N, numeric timestamps
All items or pages-a, --allSelects every applicable item (all projects; every entry for remove) or fetches every page (bounded, cancelable); one meaning per command, stated in help--team-level, --everything
Search-q, --query <TEXT>Free-text search; define matching--search, -s
Filters--<field> <VALUE>One option per filterable field. Prefer comma-separated values for OR within a field. Preserve existing repeated forms for compatibility. --query may accept a documented search syntax; filters never do.--filter <EXPR> mini-languages
Grouping--group-by <DIM>Prefer comma-separated dimensions for aggregated results. Preserve existing repeated forms for compatibility. Help lists the valid dimensions and the default--by, --dimension, --split
Follow-f, --followStream until stopped; --no-follow where following is the default--watch, -w, --tail, --stream
Waiting--no-wait, --wait, --timeout <DURATION>See Long-running work & cancellation--wait-timeout
File output-o, --output <PATH>File or directory destination; - means stdout--out. -o json or `--output json
Payload input--file <FILE>, --value <VALUE>, --data <JSON>- means stdin--json as input, --body, --items for the whole payload
Field selection--fields <FIELDS>Standard on JSON commands with a result schema; an unknown field lists the valid ones
On/off setting--<setting> / --no-<setting>Boolean presence options`--<setting> on
Name--name <NAME>Display or resource name when it isn’t the positional-n
Description--description <TEXT>-d
Message--message <TEXT>Free text attached to an action
Metadata--meta <KEY=VALUE>Repeatable--metadata, -m
Label--label <LABEL>Repeatable--tag for the same concept, -l
Consent digest--effects-digest <DIGEST>Guard a rerun against changed effects (Machine errors)
Browser--no-openSuppress opening a browser--open as a string
Money--amount <USD>Currency amounts--limit, --budget for money

The time-range names under “Never” apply to ranges. An option for a single point in time is named for its field: flags rollout --start, ai-gateway leaderboard --date.

Short options

A short option (- and one case-sensitive letter) has one meaning and one value type across the CLI, so muscle memory from one command is safe in every other. Short forms are for frequent, low-risk inputs. Options that override safety or change what a command does (--force, --dry-run) never get one, so a typo can’t trigger them. -y is the one consent shortcut, because it’s universal.

ShortLongType
-h--helpboolean
-v--versionboolean
-d--debugboolean
-t--tokenstring
-S--scopestring
-A--local-configstring
-Q--global-configstring
-a--allboolean
-e--environmentstring
-f--followboolean
-n--limitnumber
-o--outputstring
-p--projectstring
-q--querystring
-s--sincestring
-u--untilstring
-y--yesboolean
  • Use no other letters. To reserve one, add it to this table in the same change, with a reason it’s needed CLI-wide.
  • A command accepts a short option only if it supports that input. -p means project everywhere, or nowhere.
  • A destructive or severe command rejects -a; --all must be written in full.
  • The one exception is vercel api, which mirrors gh api (-X method, -H header, -F typed field, -f raw field, -i include headers), so muscle memory transfers.

Command index

Every public command. “Kind” follows the grammar and naming rules; leaf actions use the verbs, and * marks a default action. Parenthesized command tokens are accepted aliases, relative to the row’s group unless written as a full path; other parenthesized text is a note.

Workflows & tools

CommandKindNotes
vercel [path], deploy [path]workflowBare vercel deploys the current directory.
dev [dir]workflowLocal development server
buildworkflowLocal build into .vercel/output
linkworkflowLink a directory to a project. link add adds a project in a monorepo
pull [path]workflowPull environment variables and settings into .vercel/
init [example] [dir]workflowCreate a project from an example
openworkflowOpen the linked project in the dashboard
login, logout, signup, whoamiworkflowSession
setupworkflowSet up coding agents: setup plugin, setup gateway (vercel ai-gateway setup), setup skills, setup mcp (vercel mcp)
skills [query]workflowDiscover agent skills for this project
token-pass [setup] (tokenpass)shortcutai-gateway coding-agents setup --token-pass; runs setup when bare and forwards its options
agent initworkflowGenerate an AGENTS.md
upgrade [version]shortcutcli upgrade
install <integration>shortcutintegrations add
switch [team]shortcutteams switch
list, inspect, promote, rollback, redeployshortcutdeployments <action>
remove (rm)aliasUntaught alias of deployments delete
feedback [note]workflowSend feedback with a note or --field <KEY=VALUE>. No login or project required
api [endpoint]toolAuthenticated API requests; api list lists endpoints
curl <path>, httpstat <path>toolRequests to deployments with protection bypass
bisecttoolFind the deployment that introduced a problem
changelogtoolLatest product updates; changelog search <query>
health (status-page)toolPlatform status, active incidents, and incidents resolved in the last 7 days, from the public status page
`logs [runtimerequests] (log`)tool
help [command]toolHelp; help search <query> finds commands by task

Groups & products

CommandLeaf actions
deploymentslist*, inspect (--logs prints build logs; --wait), delete (remove), promote, promote status, rollback, rollback status, redeploy
projects (project)list*, create (add), inspect, update, rename, delete (remove), pause, resume, token; `members list
domains (domain)list*, add, inspect, remove, transfer (move), verify, check, price, buy, renew, `auto-renew enable
dnslist*, add, inspect, update, remove, import
aliases (alias, ln)list*, set, remove
certs (cert)list*, add, issue, delete (remove)
envlist*, add, update, remove, pull, run
environments (targets, target)list*
teams (team)list*, create (add), switch, request, sso; `members list
organizations (organization)list, inspect, create, update; `teams list
tokenslist*, create (add), revoke (remove)
webhooks (webhook)list*, create, inspect (get), delete (remove)
crons (cron)list*, add, run
scheduleslist*, create, inspect (get), update, delete, enable, disable, run (invoke); executions list
deploy-hooks (deploy-hook)list*, create, delete (remove)
daemons (daemon)list*, inspect, scale; `instances list
redirects (redirect)list*, add, remove, import (upload), publish (promote), restore; versions list (list-versions)
routeslist*, add, inspect, update (edit), remove (delete), enable, disable, move (reorder), publish, discard (discard-staging), restore, export; versions list (list-versions)
commentslist*, inspect, reply, update (edit), delete, resolve, reopen, open
drains (drain)list*, inspect, create, update, pause, resume, delete
alertslist* (ls), inspect
monitorslist* (ls), add (create), inspect, update, remove, schema; `notifications list
integrations (integration)list*, add (install), remove, update, open, discover, categories, guide, balance; terms accept (accept-terms); installations list (installations)
integrations resources (integration resource, integration-resource, ir)inspect, connect, disconnect, delete (remove), claim; thresholds add (create-threshold)
storagelist*, create, inspect (get, status), update, delete, connect, disconnect
bloblist*, inspect, upload (put), download (get), copy, delete (del, remove), presign, signed-token; images upload (put-image); `stores list
global-config (edge-config)list*, create (add), inspect (get), update, delete (remove); `items list
flagslist*, create, inspect, update, delete (remove), set, enable, disable, archive, unarchive, split, rollout, override, prepare, datafile, open, evaluations; targeting enable (use-targeting); `rules list
firewalloverview*, status, diff, publish, discard; `rules list
gitconnect, disconnect
kmslist*, create (add), inspect, update, delete (remove), import; `keys create
ai-gatewaycoding-agents setup; `api-keys list
microfrontends (mf)pull; `groups list
rolling-releases (rolling-release, rr)inspect (fetch), update (configure), start, approve, abort, complete
connectors (connect)list*, create, update, delete (remove), connect, disconnect (attach, detach), open, token, discover, categories; tokens revoke (revoke-tokens); `contacts list
sandboxDelegated to the Sandbox CLI. It owns its tree but follows this registry and renders help in the standard layout
vcrlist* (ls), create (add), inspect, delete (rm), build, push, login, update (config); `images list
cienable, list (ls), inspect, logs, grep, rerun
agent-runslist*, inspect, trace, projects
metrics [metric]query*, schema
traces [request-id]inspect* (get), search, capture (create; shortcut for curl --trace); `config list
activitylist* (ls), types
cachepurge, invalidate, dangerously-delete
securitycheck*
billingusage (vercel usage), contract (vercel contract), `budgets list
cliupgrade, versions installed*`

Where groups overlap:

  • Budgets: Spend Management budgets live in billing budgets (team) and ai-gateway budgets (gateway monthly spend limits); each help page names the other.
  • Alerts: budget alerts (billing budgets alerts) are Spend Management thresholds reached; alerts are observability alerts; firewall alerts are Vercel Firewall alerts. Each help page names the others.
  • Schedules: crons are defined in config; schedules are managed through the API.
  • Environments: env manages environment variables; environments manages custom environments.
  • Storage: storage is the cross-product view; blob and global-config manage their own stores.