JSON in, JSON out, no interactivity. Lists are NDJSON (one object per line, then
{"@pagination":…} when more pages exist); single resources are NDJSON by
default (one line — pass --format json for the pretty object).
Errors are JSON on stderr with fixable_by: agent|human|retry and a hint.
Get (single + multi). get <id>... takes one or more ids and returns one
result per id, in input order. Default output is NDJSON: one line per id — the
record, or {"@unresolved":{"id","reason","fixable_by","hint"?}} for an id that
couldn't be resolved (e.g. not found / bad id). --format json|yaml collapses
to one {"data":[…], "@unresolved":[…]} envelope. Item-level misses stay on
stdout and exit 0; only a command-level failure (auth, network) goes to stderr
with exit 1 and empty stdout.
env get <project> <key>... fixes the project scope first, then resolves 1..N
keys from that project's vars — one NDJSON record (or @unresolved) per key.
Safety: read freely (list, get, checks, routes, current, logs,
runtime-logs, diff, inspect, records, cert, protection, projects,
transfer, consumption, and the firewall/drains reads). Do not promote,
rollback, cancel, redeploy, change env vars, add/remove/verify domains, change
aliases, or purge the cache unless the user explicitly asked — those require
--yes.
Select the credential and team separately
A Vercel token can reach one or more teams, depending on its grants.
--scope never switches credentials, even when a credential has the same label.
--auth <label>selects a stored credential. Token precedence:--auth→$VERCEL_TOKEN→ stored default.--scope <team-slug|id>selects the team. Scope precedence:--scope→$VERCEL_SCOPE→$VERCEL_TEAM_ID→ stored default → personal account.
Empty selectors fall through; --scope "" does not force the personal account.
The token is a secret stored in the Keychain, never printed or readable through
the CLI. Never retrieve the token, print $VERCEL_TOKEN, or ask for a token in chat.
Labels and team identifiers can still be private; use placeholders in shared examples.
For a scope 403, unexpected account, or re-authentication hint, read
Diagnose selection before replacing a token.
scope current ignores environment overrides and --auth; auth test verifies
the owner, not team access. Diagnose with per-command selectors; change persistent
defaults only when requested.
Setup (once)
agent-vercel auth add --form # human pastes the token into an OS dialog (preferred)
# …or, non-interactively:
export VERCEL_TOKEN=... # token from vercel.com/account/tokens
agent-vercel auth add personal # stores it in the Keychain (label optional); verifies + records username
agent-vercel auth test # re-verify any time (GET /v2/user)
agent-vercel scope list # teams this credential can reach
agent-vercel scope set-default acme # default scope for later calls
Prefer auth add --form — it keeps the token out of the conversation and shell
history. Never ask the user to paste a token into chat.
Triage (reading)
agent-vercel deployment list --state ERROR --target production --since 24h # failed prod deploys
agent-vercel deployment list --project my-app --limit 10
agent-vercel deployment current my-app # what is live in prod (+ rolling release)
agent-vercel deployment get dpl_… # one deployment, compact
agent-vercel deployment checks dpl_… --failed # which CI checks are blocking/failing
agent-vercel deployment routes dpl_… # compiled redirects/rewrites/headers (loop triage)
agent-vercel deployment logs dpl_… --status 5xx # build logs, filtered
agent-vercel deployment runtime-logs dpl_… --level error --path /api
agent-vercel project crons my-app # scheduled jobs + whether crons are on
agent-vercel project custom-environments my-app # discover custom envs (slug, branch, domains)
agent-vercel project protection my-app # why a preview/prod URL 401s (SSO/password/trusted-ips)
agent-vercel project routes my-app --diff # authored routing rules (staged-vs-live)
agent-vercel env diff my-app # prod-vs-preview env var diff
agent-vercel env shared list # team-level shared env vars (across projects)
agent-vercel domain inspect example.com # DNS + SSL/ACME readiness (configured_by, challenges)
agent-vercel domain cert list --expiring 30 # certs expiring within 30 days
agent-vercel domain projects example.com # which projects this domain is on (wrong-project triage)
agent-vercel domain transfer example.com # registrar transfer status
agent-vercel alias list dpl_… # aliases + protection state
agent-vercel firewall config my-app # active WAF rules / managed rulesets / IP blocks
agent-vercel firewall attack-status my-app --since 7 # active attack / DDoS anomalies
agent-vercel billing charges --by region # spend broken down by region
agent-vercel billing consumption # consumed volume by service (units, not just $)
agent-vercel webhook list --project prj_… # which events fire where
agent-vercel drains list --project prj_… # where log/trace/analytics data is shipped
agent-vercel edge-config items ecfg_… # live feature flags / config values
agent-vercel --scope my-team scope member list # who has access to the team
deployment list is cross-project and filterable — the main thing the
vercel CLI cannot do. Pass --scope <team> to look at another team.
Acting (gated — only when asked)
agent-vercel deployment promote dpl_… --yes # repoint prod to this deployment
agent-vercel deployment rollback dpl_… --yes
agent-vercel env set my-app KEY value --environment production --yes
agent-vercel alias set dpl_… app.example.com --yes
agent-vercel cache purge my-app --tag products --yes # invalidate CDN cache by tag
Without --yes, a gated command returns a description of what would happen —
show that to the user before retrying with --yes.
Escape hatch
agent-vercel api call GET /v6/deployments --query 'state=ERROR&limit=5'
agent-vercel api call POST /v2/deployments/dpl_…/aliases --body '{"alias":"x"}' --yes
Read references when the examples stop covering the task
- Read references/commands.md for commands or flags absent
from the examples, credential/scope diagnosis, or a command's
--yesgating. - Read references/output.md when handling pagination,
unresolved ids, output formats, compact vs
--fullpayloads, timestamps or truncation.
Live docs from the binary: agent-vercel usage is the overview;
agent-vercel <domain> usage has per-domain detail.