vercel curl

The vercel curl command works like curl, but automatically handles deployment protection bypass tokens for you. When your project has Deployment Protection enabled, this command lets you test protected deployments without manually managing bypass secrets.

The command runs the system curl command with the same arguments you provide, but adds an x-vercel-protection-bypass header with a valid token. This makes it simple to test API endpoints, check responses, or debug issues on protected deployments.

vercel curl [path]

Make a GET request to your production deployment:

vercel curl /api/hello

Send a POST request with JSON data. Use the -- separator to pass flags through to the underlying curl:

vercel curl /api/users -- --request POST --header "Content-Type: application/json" --data '{"name":"John"}'

Test a specific deployment by its URL:

vercel curl /api/status --deployment https://my-app-abc123.vercel.app

See detailed request information by passing curl's -v flag after --:

vercel curl /api/data -- -v

Capture a session trace for the request and print the trace request ID:

vercel curl --trace /api/hello

After the request completes, the command prints a vercel traces get command you can run to inspect the trace. See vercel traces for details.

When you run vercel curl:

1. The CLI finds your linked project (or you can specify one with --scope)
2. It gets the latest production deployment URL (or uses the deployment you specified)
3. It retrieves or generates a deployment protection bypass token
4. It runs the system curl command with the bypass token in the x-vercel-protection-bypass header

The command requires curl to be installed on your system.

These are options that only apply to the vercel curl command. To pass flags through to the underlying curl command, place them after the -- separator.

The --deployment option lets you specify a deployment ID or URL to request instead of using the production deployment.

vercel curl /api/hello --deployment https://my-app-abc123.vercel.app

The --protection-bypass option lets you provide your own deployment protection bypass secret instead of automatically generating one. This is useful when you already have a bypass secret configured.

vercel curl /api/hello --protection-bypass your-secret-here

You can also use the VERCEL_AUTOMATION_BYPASS_SECRET environment variable:

export VERCEL_AUTOMATION_BYPASS_SECRET=your-secret-here
vercel curl /api/hello

The --yes option, shorthand -y, skips the confirmation prompt when linking is required. Use it in non-interactive environments like CI, or run vercel link ahead of time to link your project and avoid the prompt entirely.

vercel curl /api/hello --yes

The --trace option captures a request trace for the request and prints the trace request ID once the response completes. When targeting a production deployment, the command prompts for confirmation unless --yes is set.

vercel curl --trace /api/hello

The --json option only applies with --trace. Instead of streaming the response body to stdout, the command captures it and emits a JSON envelope with the response body and request ID:

vercel curl --trace --json /api/hello

{
  "response": "...",
  "requestId": "abc-123"
}

Make sure curl is installed on your system:

# macOS (using Homebrew)
brew install curl
 
# Ubuntu/Debian
sudo apt-get install curl
 
# Windows (using Chocolatey)
choco install curl

Make sure you're in a directory with a linked Vercel project and that the project has at least one deployment:

# Link your project
vercel link
 
# Deploy your project
vercel deploy

If automatic token creation fails, you can create a bypass secret manually in the Vercel Dashboard:

1. Go to your project's Settings → Deployment Protection
2. Find "Protection Bypass for Automation"
3. Click "Create" or "Generate" to create a new secret
4. Copy the generated secret
5. Use it with the --protection-bypass flag or VERCEL_AUTOMATION_BYPASS_SECRET environment variable

When using --deployment, verify that:

• The deployment ID or URL is correct
• The deployment belongs to your linked project
• The deployment hasn't been deleted

The following global options can be passed when using the vercel curl command:

• --cwd
• --debug
• --global-config
• --help
• --local-config
• --no-color
• --non-interactive
• --scope
• --team
• --token
• --version

For more information on global options and their usage, refer to the options section.

• Deployment Protection
• vercel deploy
• vercel inspect