ContextQMD
Back to Vercel

`vercel curl` Command

packages/cli/src/commands/curl/README.md

16.1.26.6 KB
Original Source

vercel curl Command

A powerful passthrough command for curl that simplifies testing your Vercel deployments by automatically handling deployment URLs and protection bypass authentication.

Why Use This?

Testing API endpoints on Vercel deployments typically requires:

  • Finding the deployment URL manually
  • Managing protection bypass secrets
  • Constructing full URLs with proper headers

vercel curl automates all of this, letting you focus on testing your APIs.

Usage

bash
vercel curl <path> [options] [-- <curl-args>]

Arguments

  • path (required): The API path to request
    • Can start with / (e.g., /api/hello) or without (e.g., api/hello)
    • Automatically normalized to include leading slash
    • Must be a relative path — do not pass a full URL. To target a specific deployment base URL, use --deployment <id>

Options

  • --deployment <id|url>: Target a specific deployment by ID or URL

    • Accepts IDs with or without the dpl_ prefix, or a full deployment URL
    • Examples: dpl_ERiL45NJvP8ghWxgbvCM447bmxwV, ERiL45NJvP8ghWxgbvCM447bmxwV, or https://your-project-abc123.vercel.app
    • The dpl_ prefix is automatically added for IDs when omitted

  • --protection-bypass <secret>: Provide a protection bypass secret

    • Required for deployments with Vercel Protection enabled
    • Alternatively, set the VERCEL_AUTOMATION_BYPASS_SECRET environment variable

  • --help: Display help information

Curl Arguments

All arguments after -- are passed directly to the curl command:

bash
vercel curl /api/endpoint -- --header "Content-Type: application/json" --request POST --data '{"key":"value"}'

Examples

Basic GET Request

bash
vercel curl /api/hello

Equivalent to:

bash
curl --url https://your-project-abc123.vercel.app/api/hello \
     --header "x-vercel-protection-bypass: <auto-generated-secret>"

POST Request with JSON Data

bash
vercel curl /api/users -- \
  --request POST \
  --header "Content-Type: application/json" \
  --data '{"name": "John", "email": "[email protected]"}'

Target a Specific Deployment

bash
# Test a specific deployment by ID
vercel curl /api/status --deployment ERiL45NJvP8ghWxgbvCM447bmxwV

# Or with the dpl_ prefix
vercel curl /api/status --deployment dpl_ERiL45NJvP8ghWxgbvCM447bmxwV

# Or by passing a full deployment URL
vercel curl /api/status --deployment https://your-project-abc123.vercel.app

Custom Headers and Methods

bash
vercel curl /api/test -- \
  --request PUT \
  --header "Content-Type: application/json" \
  --header "X-Custom-Header: value" \
  --data '{"updated": true}'

Using Your Own Protection Bypass Secret

bash
vercel curl /api/protected \
  --protection-bypass your-secret-key \
  -- --request GET

Complex Request Example

bash
vercel curl /api/ziltoid/visitPlanet -- \
  --request POST \
  --header "Content-Type: application/json" \
  --data '{
    "nebulo": 9,
    "omniscient": false,
    "ultimateCupOfCoffee": true,
    "time": "6 earth minutes"
  }'

How It Works

The command follows this workflow:

1. Deployment URL Resolution

The target deployment URL is determined automatically:

  • With --deployment flag: Fetches the specified deployment's URL

    • The dpl_ prefix is automatically added if not provided
    • Example: ERiL45NJvP8ghWxgbvCM447bmxwV → dpl_ERiL45NJvP8ghWxgbvCM447bmxwV

  • Without --deployment flag: Uses the latest deployment from your linked project

    • Prefers the most recent production deployment
    • Falls back to the latest preview deployment if no production exists

2. Protection Bypass Handling

For deployments with Vercel Protection enabled, the command automatically manages authentication:

Priority order:

  1. --protection-bypass flag value (if provided)
  2. VERCEL_AUTOMATION_BYPASS_SECRET environment variable
  3. Existing automation bypass token from project settings
  4. Attempts to create a new automation bypass token via API

If automatic token creation fails, you'll see instructions for manual setup.

3. Request Execution

The command constructs and executes the curl command with:

  • Target URL: https://<deployment-url><path>
  • Protection header: x-vercel-protection-bypass: <secret> (if available)
  • Your curl args: All arguments after -- are passed directly to curl

Protection Bypass Setup

Automatic (Recommended)

The command will attempt to create an automation bypass token automatically. This works for most Vercel plans.

Manual Setup

If automatic creation isn't available or fails:

  1. Navigate to your project:

  2. Access Deployment Protection settings:

    • Go to Settings → Deployment Protection

  3. Generate automation bypass secret:

    • Look for "Protection Bypass for Automation"
    • Click "Create" or "Generate" to create a new secret
    • Copy the generated secret

  4. Use the secret:

    Option A - With the flag:

    bash
    vercel curl /api/endpoint --protection-bypass your-secret-here

    Option B - With environment variable:

    bash
    export VERCEL_AUTOMATION_BYPASS_SECRET=your-secret-here
vercel curl /api/endpoint

Troubleshooting

"curl command not found"

Ensure curl is installed on your system:

bash
# macOS (using Homebrew)
brew install curl

# Ubuntu/Debian
sudo apt-get install curl

# Windows (using Chocolatey)
choco install curl

"No deployment found for the project"

Make sure:

  • You're in a directory with a linked Vercel project (run vercel link if needed)
  • Your project has at least one deployment (run vercel deploy to create one)

"Failed to get deployment protection bypass token"

This means automatic token creation failed. Follow the manual setup steps above to create a protection bypass secret.

"No deployment found for ID"

When using --deployment:

  • Verify the deployment ID is correct
  • Check that the deployment belongs to your linked project
  • Ensure the deployment hasn't been deleted

"Path must be relative (not a full URL)"

When invoking vercel curl, pass only the API path (e.g., /api/hello).

  • Don’t include the protocol or host (e.g., https://my-app.vercel.app/api/hello)
  • If you need to target a particular deployment, use --deployment <id|url> and keep <path> relative

Requirements

  • curl: Must be installed and available in your system PATH
  • Vercel project: Must be linked (run vercel link in your project directory)
  • Deployment: At least one deployment must exist for the project