# Agent Vercel

> Triage Vercel deployments, builds, logs, domains, and spend: what is live in production including rolling releases, build and runtime logs, env var diffs across environments, domains, DNS, certs, and the Firewall (WAF), CDN cache purge by tag, usage breakdowns, aliases, and raw REST API calls. Read by default; state-changing actions are gated behind --yes. Use when asked why a deployment failed, which deploy is live, to compare env vars, fix a misconfigured domain or cert, promote or roll back a deployment, or see what drives Vercel spend.

- Skill: `shhac/agent-vercel` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add shhac/agent-vercel`
- Raw SKILL.md: https://api.skillmd.com/api/skills/shhac/agent-vercel/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: shhac (https://skillmd.com/u/shhac)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/shhac/agent-vercel

---


# agent-vercel

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`.

## Credential vs scope (read this first)

One Vercel access **token** reaches many **teams**. They are separate axes:

- `auth` manages the credential (the **secret**; currently an access token) —
  kept in the macOS Keychain, never printed. There is no command to read it back
  out; never ask the user to paste a token into chat, and don't try to retrieve
  one.
- `scope` selects which team (account) to act on — not a secret.

Pick per command: `--auth <label>` (which credential) and
`--scope <team-slug|id>` (which team; omit for the default / personal account).

## Setup (once)

```bash
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)

```bash
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)

```bash
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

```bash
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
```

## More detail

- [references/commands.md](references/commands.md) — full command map, flags, and which are `--yes`-gated
- [references/output.md](references/output.md) — NDJSON + meta-line contract, compact vs `--full`, timestamps, pagination

Live docs from the binary: `agent-vercel usage` is the overview;
`agent-vercel <domain> usage` has per-domain detail.