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 [url|path]

The argument can be any of the following:

• A full URL, such as https://my-app-abc123.vercel.app/api/hello.
• A bare hostname, such as my-app-abc123.vercel.app/api/hello. The CLI adds https:// automatically.
• An API path, with or without a leading slash, such as /api/hello or api/hello. Relative paths target the linked project's latest production deployment.

Make a GET request to your production deployment:

vercel curl /api/hello

Pass a full URL to request a protected deployment directly. The CLI resolves the owning project from the URL to source the protection bypass token, so no linked project is required:

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

Pass curl flags directly to send a POST request with JSON data:

vercel curl /api/users -X POST -H "Content-Type: application/json" -d '{"name":"John"}'

When a curl flag collides with one of vercel curl's own options, use the -- separator and place the curl flag after it. For example, curl has its own --json flag, which also belongs to vercel curl, so pass curl's version after --:

vercel curl /api/users -- --json '{"name":"John"}'

Test a specific deployment by its URL:

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

Pass curl's -v flag directly to see detailed request information:

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 --project)
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

When you pass a full URL or bare hostname, the CLI resolves the deployment's owning project from the URL to source the protection bypass token, so a linked project is not required.

The CLI selects the bypass token in the following priority order:

1. The --protection-bypass flag
2. The VERCEL_AUTOMATION_BYPASS_SECRET environment variable
3. An existing or newly created automation bypass token from the project's settings

Any flag you pass that is not one of vercel curl's own options is passed through to the underlying curl, so you don't need the -- separator for most curl flags. Use -- only when a curl flag collides with a vercel curl option: --deployment, --protection-bypass, --yes, --trace, --json, --help, or --url. Everything after -- is always passed to curl.

The command requires curl to be installed on your system.

These are options that only apply to the vercel curl command. When a curl flag collides with one of these option names, place it after the -- separator so it is passed through to curl.

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