vercel__vercel-plugin/commands/status.md.tmpl

---
description: Show the status of the current Vercel project — recent deployments, linked project info, and environment overview.
---

# Vercel Project Status (Doctor)

Comprehensive project health check. Diagnoses deployment state, environment configuration, domains, and build status.

## Preflight

1. Check for `.vercel/project.json` in the current directory (or nearest parent).
   - **If found**: read `projectId` and `orgId` to confirm linkage. Print project name.
   - **If not found**: print a clear message:
     > This project is not linked to Vercel. Run `vercel link` to connect it, then re-run `/status`.
     Stop here — remaining steps require a linked project.
2. Verify `vercel` CLI is available on PATH. If missing, suggest `npm i -g vercel`.
3. Detect monorepo markers (`turbo.json`, `pnpm-workspace.yaml`). If present, note which package scope is active.

## Plan

Gather project diagnostics using MCP reads where available, CLI as fallback:

1. Fetch recent deployments (last 5).
2. Inspect the latest deployment for build status and metadata.
3. List environment variables per environment (counts only — never print values).
4. Check domain configuration and status.
5. Read `vercel.json` for configuration highlights.

No destructive operations — this command is read-only.

## Commands

### 1. Recent Deployments

```
vercel ls --limit 5
```

Extract: deployment URL, state (READY / ERROR / BUILDING), target (production / preview), created timestamp.

### 2. Latest Deployment Inspection

```
vercel inspect <latest-deployment-url>
```

Extract: build duration, function count, region, framework detected, Node.js version.

### 3. Environment Variable Counts

```
vercel env ls
```

Count variables per environment (Production, Preview, Development). **Never echo variable values.**

Present as:

| Environment | Count |
|-------------|-------|
| Production  | N     |
| Preview     | N     |
| Development | N     |

### 4. Domain Status

```
vercel domains ls
```

For each domain: name, DNS configured (yes/no), SSL valid (yes/no).

### 5. Configuration Highlights

Read `vercel.json` (if present) and summarize:

- Framework preset
- Build command overrides
- Function configuration (runtime, memory, duration)
- Rewrites / redirects count
- Cron jobs defined
- Headers or middleware config

If `vercel.json` does not exist, note "No vercel.json found — using framework defaults."

### 6. Observability Diagnostics

Check the project's observability posture — drains, error monitoring, analytics instrumentation, and drain security.

#### 6a. Drains Configured?

Use MCP `list_drains` if available, or the REST API:

```bash
curl -s -H "Authorization: Bearer $VERCEL_TOKEN" \
  "https://api.vercel.com/v1/drains?teamId=$TEAM_ID" | jq '.drains | length'
```

- **If drains exist**: list drain count, types (JSON/NDJSON/Syslog), and statuses.
- **If zero drains**: note "No drains configured" and flag as a gap for production observability.

#### 6b. Errored Drains?

For each drain returned, check the status field. If any drain shows an error or disabled state:

```
⚠️ Drain "<drain-url>" is in error state.
Remediation:
  1. Verify the endpoint URL is reachable and returns 2xx.
  2. Check that the endpoint accepts the configured format (JSON/NDJSON/Syslog).
  3. Test the drain: POST /v1/drains/<drain-id>/test
  4. If unrecoverable, delete and recreate the drain.
```

#### 6c. Analytics Instrumentation Present?

Scan the project source for `@vercel/analytics` and `@vercel/speed-insights` imports:

- Check `package.json` dependencies for `@vercel/analytics` and `@vercel/speed-insights`.
- If missing either package, flag:
  > Analytics/Speed Insights not detected. See `⤳ skill: observability` for setup.

#### 6d. Drain Signature Verification

<!-- Sourced from observability skill: Drains > Security: Signature Verification -->
{{include:skill:observability:Drains > Security: Signature Verification}}

Check whether the project has a `DRAIN_SECRET` env var set via `vercel env ls`. If drains are configured but no signature secret is found, flag as a security gap.

#### 6e. Fallback Guidance (No Drains)

<!-- Sourced from observability skill: Drains > Fallback Guidance (No Drains) -->
{{include:skill:observability:Drains > Fallback Guidance (No Drains)}}

#### Observability Decision Matrix

<!-- Sourced from observability skill: Decision Matrix -->
{{include:skill:observability:Decision Matrix}}

## Verification

Confirm each data source returned successfully:

- [ ] Deployment list retrieved (count > 0 or "no deployments yet")
- [ ] Latest deployment inspected (or skipped if no deployments)
- [ ] Environment variable counts retrieved per environment
- [ ] Domain list retrieved (or "no custom domains")
- [ ] vercel.json parsed (or "not present")
- [ ] Drain status checked (count, errored drains identified)
- [ ] Analytics/Speed Insights instrumentation detected (or gap flagged)
- [ ] Drain signature secret checked (if drains configured)

If any check fails, report the specific error and continue with remaining checks.

## Summary

Present the diagnostic report:

```
## Vercel Doctor — Project Status

**Project**: <name> (<org>)
**Latest Deployment**: <url> — <state> (<target>, <timestamp>)
**Build**: <duration>, <framework>, Node <version>

### Deployments (last 5)
| URL | State | Target | Created |
|-----|-------|--------|---------|
| ... | ...   | ...    | ...     |

### Environment Variables
| Environment | Count |
|-------------|-------|
| Production  | N     |
| Preview     | N     |
| Development | N     |

### Domains
| Domain | DNS | SSL |
|--------|-----|-----|
| ...    | ... | ... |

### Config Highlights
- <key settings from vercel.json>

### Observability
| Check | Status |
|-------|--------|
| Drains configured | N configured (N healthy, N errored) |
| Analytics (`@vercel/analytics`) | ✓ installed / ✗ not found |
| Speed Insights (`@vercel/speed-insights`) | ✓ installed / ✗ not found |
| Drain signature secret | ✓ DRAIN_SECRET set / ⚠ missing |
```

## Next Steps

Based on the diagnostic results, suggest relevant actions:

- **Build errors** → "Run `/deploy` to trigger a fresh build, or check `vercel logs <url>` for details."
- **Missing env vars** → "Run `/env list` to review, or `/env pull` to sync locally."
- **DNS not configured** → "Update your domain DNS records. See the Vercel domains dashboard."
- **No deployments** → "Run `/deploy` to create your first deployment."
- **Stale deployment** → "Your latest deployment is over 7 days old. Consider redeploying."
- **No vercel.json** → "Add a `vercel.json` if you need custom build, function, or routing configuration."
- **No drains (Hobby)** → "View logs via Dashboard or `vercel logs <url> --follow`. Upgrade to Pro for drain-based forwarding."
- **No drains (Pro+)** → "Configure drains for centralized observability. See `⤳ skill: observability` or run via REST API."
- **Errored drain** → "Test the endpoint: `POST /v1/drains/<id>/test`. Check URL reachability and format compatibility."
- **Missing analytics** → "Install `@vercel/analytics` and add `<Analytics />` to your root layout."
- **Missing speed insights** → "Install `@vercel/speed-insights` and add `<SpeedInsights />` to your root layout."
- **Missing drain secret** → "Set `DRAIN_SECRET` env var. Without it, drain endpoints can't verify payload authenticity."