Deploy Next.js with the Best CLI for AI Agents

---
name: deploy-nextjs-workflow
description: "Build locally, create a preview deployment, verify the result, and keep production promotion behind an explicit approval."
---

# Deploy a Next.js application

## Intended outcome

Produce a working preview and a release-ready report without silently changing production.

## Evidence boundary

- Tool status distinguishes `docs-verified` material from independent execution; the two are not interchangeable.
- The current registry does not attribute a tool execution to a particular agent, so compatible agents cannot be called tested agents.
- Reconfirm the target account, environment, version, and official documentation before execution.
- Never auto-execute an R2, R3, or confirmation-marked step; obtain explicit approval immediately before it runs.

## Recommended tools, installation, and authentication

- **Vercel CLI** (evidence: `docs-verified`, docs checked: `2026-07-10`, no independently executed version recorded)
  - Install: `npm install --global vercel`
  - Authentication: browser login, access token
  - Minimum permissions: Use a token scoped to the target team and project; keep production promotion separate.
- **Cloudflare Wrangler** (evidence: `verified`, docs checked: `2026-07-10`, independently tested version 4.87.0 recorded)
  - Install: `npm install --save-dev wrangler`
  - Authentication: OAuth, API token
  - Minimum permissions: Use an API token limited to the required account, zone, and Worker resources.
- **GitHub CLI** (evidence: `verified`, docs checked: `2026-07-10`, independently tested version 2.86.0 recorded)
  - Install: `brew install gh`
  - Authentication: OAuth, personal access token, GitHub Actions token
  - Minimum permissions: Use a read-only or fine-grained token limited to the required repositories.
- **jq** (evidence: `verified`, docs checked: `2026-07-10`, independently tested version jq-1.7.1-apple recorded)
  - Install: `brew install jq`
  - Authentication: not required for the base operation
  - Minimum permissions: No service credential is required; restrict filesystem and network access to the task.

## Input contract

- Repository path
- package scripts
- deployment target
- scoped deployment credentials

## Output contract

- Build result
- preview URL
- verification notes
- production command awaiting approval

## Safe workflow

1. **Inspect the project** — Read package scripts, framework configuration, and current Git state before choosing a deployment target.
   - Input: Repository files and Git metadata
   - Output: Build command and deployment plan
   - Risk: `read-only`
   - Command: `jq '.scripts' package.json && git status --short`
2. **Build and create a preview** — Run the project build, then use the provider CLI to create a non-production preview.
   - Input: Build command and preview credentials
   - Output: Preview deployment URL and CLI logs
   - Risk: `remote-write`
   - Command: `pnpm build && vercel deploy`
3. **Verify before promotion** — Open the preview, exercise critical routes, and report any warnings before proposing production promotion.
   - Input: Preview URL and acceptance checks
   - Output: Pass/fail report and proposed production command
   - Risk: `read-only`

## Ask before proceeding

- Creating a preview in a shared account
- Running a production deployment
- Changing domains, secrets, or environment variables

## Rollback

- Keep the previous production deployment available
- Promote the last known-good deployment through the provider
- Revert the release commit if the application itself is faulty

## Official sources

- [Vercel CLI documentation](https://vercel.com/docs/cli) — Official CLI documentation for project linking, builds, deployments, and logs.
- [Cloudflare Wrangler documentation](https://developers.cloudflare.com/workers/wrangler/) — Official Wrangler command and configuration documentation for Workers.
- [GitHub CLI manual](https://cli.github.com/manual/) — Official command, authentication, JSON field, and workflow documentation.