vercel firewall

The vercel firewall command is used to configure the Vercel Firewall from the command line, including custom rules, IP blocks, system bypass rules, attack challenge mode, and system mitigations. You can match traffic with condition parameters and actions, stage updates to rules and IP blocks as drafts, and publish them when you are ready.

For more information about Vercel Firewall, see the Vercel Firewall documentation.

The vercel firewall command supports the following operations:

• overview - Show a summary of your project's firewall configuration
• rules - Manage custom firewall rules
• ip-blocks - Manage IP blocks
• system-bypass - Manage system bypass rules
• attack-mode - Enable or disable Attack Mode
• system-mitigations - Pause or resume automatic DDoS mitigation
• Staging and publishing - Review, publish, or discard staged changes with diff, publish, and discard

Custom rule and IP block changes are staged until you run publish. System bypass, attack challenge mode, and system mitigations apply immediately.

Show a summary of your project's firewall configuration, including active rules, IP blocks, bypasses, attack challenge mode status, and unpublished draft changes.

vercel firewall overview

Options:

• --json: Output as JSON

Custom rules let you define traffic policies based on request attributes. Use them to block abusive traffic, rate limit APIs, challenge suspicious requests, redirect legacy paths, or log traffic for monitoring. Rule changes are staged as drafts and require publishing.

List all custom firewall rules, including any unpublished draft changes. Draft additions, removals, and modifications are annotated in the output.

vercel firewall rules list

Options:

• -e, --expand: Show full condition and action details for each rule
• --json: Output as JSON

Examples:

# List all rules
vercel firewall rules list
 
# Show full details
vercel firewall rules list --expand

Show the full configuration of a custom firewall rule, including conditions, action, and rate limit settings.

vercel firewall rules inspect <name-or-id>

Options:

• --json: Output as JSON

Examples:

# Inspect by name
vercel firewall rules inspect "Block bots"
 
# Inspect by ID
vercel firewall rules inspect rule_abc123

Create a new custom firewall rule. You can create rules using four modes: AI (natural language), interactive wizard, command-line flags, or a JSON payload.

vercel firewall rules add [name] [options]

Options:

• --ai <PROMPT>: Generate a rule from natural language (interactive only)
• --json <PAYLOAD>: Create a rule from a full JSON payload
• --condition <JSON>: Add a condition as a JSON object (repeatable). Multiple conditions are combined with AND
• --or: Start a new OR group. Conditions before --or are combined with AND, conditions after form a separate group
• --action <TYPE>: Action: deny, challenge, log, bypass, rate_limit, redirect
• --duration <DURATION>: Action duration: 1m, 5m, 15m, 30m, 1h
• --description <TEXT>: Rule description (max 256 characters)
• --disabled: Create the rule in a disabled state
• --rate-limit-window <SECONDS>: Rate limit time window in seconds, 10 to 3,600 (required for rate_limit)
• --rate-limit-requests <NUMBER>: Max requests per window, 1 to 10,000,000 (required for rate_limit)
• --rate-limit-keys <KEY>: What to count by: ip (default), ja4, header:<name> (repeatable)
• --rate-limit-algo <ALGO>: Algorithm: fixed_window (default), token_bucket
• --rate-limit-action <ACTION>: Action when limit is exceeded: rate_limit (default), deny, challenge, log
• --redirect-url <URL>: Redirect destination URL or path
• --redirect-permanent: Use permanent redirect (301). Default: temporary (307)
• -y, --yes: Skip the confirmation prompt

Examples:

# Interactive mode
vercel firewall rules add
 
# Generate with AI
vercel firewall rules add --ai "Rate limit /api to 100 requests per minute by IP"
 
# Create with flags
vercel firewall rules add "Block bots" \
  --condition '{"type":"user_agent","op":"sub","value":"crawler"}' \
  --action deny --yes
 
# Multiple conditions (AND)
vercel firewall rules add "Secure admin" \
  --condition '{"type":"path","op":"pre","value":"/admin"}' \
  --condition '{"type":"geo_country","op":"neq","value":"US"}' \
  --action deny --yes
 
# OR groups
vercel firewall rules add "Block methods" \
  --condition '{"type":"method","op":"eq","value":"DELETE"}' \
  --or \
  --condition '{"type":"method","op":"eq","value":"PATCH"}' \
  --action challenge --yes
 
# Rate limit
vercel firewall rules add "Rate limit API" \
  --condition '{"type":"path","op":"pre","value":"/api"}' \
  --action rate_limit \
  --rate-limit-window 60 \
  --rate-limit-requests 100 \
  --rate-limit-keys ip \
  --rate-limit-action deny --yes
 
# Redirect
vercel firewall rules add "Redirect old path" \
  --condition '{"type":"path","op":"eq","value":"/old"}' \
  --action redirect \
  --redirect-url "/new" \
  --redirect-permanent --yes
 
# Create from JSON
vercel firewall rules add --json '{"name":"Block bots","conditionGroup":[{"conditions":[{"type":"user_agent","op":"sub","value":"crawler"}]}],"action":{"mitigate":{"action":"deny"}}}' --yes

Each --condition flag takes a JSON object with a type, op, and usually a value:

# Block POST requests to /api
vercel firewall rules add "Block POST to API" \
  --condition '{"type":"path","op":"pre","value":"/api"}' \
  --condition '{"type":"method","op":"eq","value":"POST"}' \
  --action deny --yes

For header, cookie, and query types, include a key field to specify which header, cookie, or query parameter to check. Use neg: true to negate a condition:

# Challenge requests without an Authorization header
vercel firewall rules add "Require auth" \
  --condition '{"type":"header","op":"ex","key":"Authorization","neg":true}' \
  --action challenge --yes

Conditions within a group are combined with AND. Use --or between conditions to create separate groups that are combined with OR.

Edit an existing custom firewall rule. You can edit using AI, an interactive editor, command-line flags, or a JSON payload.

vercel firewall rules edit <name-or-id> [options]

Options:

• --ai <PROMPT>: Describe changes using natural language (interactive only)
• --json <PAYLOAD>: Replace the rule with a full JSON payload
• --condition <JSON>: Replace conditions (repeatable, same format as add)
• --or: Start a new OR group
• --name <NAME>: Rename the rule
• --action <TYPE>: Change action: deny, challenge, log, bypass, rate_limit, redirect
• --duration <DURATION>: Change action duration
• --description <TEXT>: Change description (use "" to clear)
• --enabled: Set the rule to enabled
• --disabled: Set the rule to disabled
• --rate-limit-window, --rate-limit-requests, --rate-limit-keys, --rate-limit-algo, --rate-limit-action: Rate limit options (same as rules add)
• --redirect-url, --redirect-permanent: Redirect options (same as rules add)
• -y, --yes: Skip the confirmation prompt

Examples:

# Interactive mode
vercel firewall rules edit "My Rule"
 
# Edit with AI
vercel firewall rules edit "My Rule" --ai "Change action to challenge"
 
# Change action
vercel firewall rules edit "My Rule" --action challenge --duration 5m --yes
 
# Rename
vercel firewall rules edit "My Rule" --name "New Name" --yes
 
# Replace conditions
vercel firewall rules edit "My Rule" \
  --condition '{"type":"path","op":"pre","value":"/new"}' --yes

Enable a disabled custom firewall rule. Stages a draft change that you must publish.

vercel firewall rules enable <name-or-id>

Disable a custom firewall rule without removing it from your firewall configuration. The rule stops matching requests after you publish the staged changes.

vercel firewall rules disable <name-or-id>

Remove a custom firewall rule. Stages a draft change that you must publish.

vercel firewall rules remove <name-or-id> --yes

Options:

• -y, --yes: Skip the confirmation prompt

Change the priority order of a custom firewall rule. Rules are evaluated in order from first to last, so position controls which rules match first. Stages a draft change that you must publish.

vercel firewall rules reorder <name-or-id> [options]

Options:

• --position <NUMBER>: Target position (1-based)
• --first: Move to the first position (highest priority)
• --last: Move to the last position (lowest priority)
• -y, --yes: Skip the confirmation prompt

Examples:

# Move to first position
vercel firewall rules reorder "My Rule" --first --yes
 
# Move to position 3
vercel firewall rules reorder "My Rule" --position 3 --yes

IP blocking lets you block specific IP addresses or CIDR ranges from accessing your project. Use it for known malicious IPs, abuse sources, or to restrict access to specific networks. IP block changes are staged as drafts and require publishing.

List all IP blocking rules, including any unpublished draft changes.

vercel firewall ip-blocks list

Options:

• --json: Output as JSON

Block an IP address or CIDR range from accessing your project. Stages a draft change that you must publish.

vercel firewall ip-blocks block <ip> [options]

Options:

• --hostname <HOST>: Scope the block to a specific hostname (default: all hosts)
• --notes <TEXT>: Add a note to the block rule
• -y, --yes: Skip the confirmation prompt

Examples:

# Block an IP
vercel firewall ip-blocks block 1.2.3.4 --yes
 
# Block a CIDR range with a note
vercel firewall ip-blocks block 10.0.0.0/24 --notes "Abuse range" --yes
 
# Block scoped to a hostname
vercel firewall ip-blocks block 1.2.3.4 --hostname example.com --yes

Remove an IP blocking rule to allow the address to access your project again. Stages a draft change that you must publish.

vercel firewall ip-blocks unblock <id-or-ip> [options]

Options:

• --hostname <HOST>: Narrow the match to a specific hostname (when the same IP is blocked on multiple hosts)
• -y, --yes: Skip the confirmation prompt

Examples:

# Unblock by IP
vercel firewall ip-blocks unblock 1.2.3.4 --yes
 
# Unblock scoped to a hostname
vercel firewall ip-blocks unblock 1.2.3.4 --hostname example.com --yes
 
# Unblock by rule ID
vercel firewall ip-blocks unblock ip_abc123 --yes

System bypass rules ensure that specific IP addresses or CIDR ranges are not blocked by system-level mitigations (such as automatic DDoS mitigation). Use them when legitimate traffic from proxies or shared networks is incorrectly flagged. These commands take effect immediately without publishing.

List all system bypass rules for IPs that skip system-level mitigations.

vercel firewall system-bypass list

Options:

• --json: Output as JSON

Add a system bypass rule so a specific IP address or CIDR range is not blocked by system-level mitigations. Takes effect immediately without publishing.

vercel firewall system-bypass add <ip> [options]

Options:

• --domain <DOMAIN>: Scope the bypass to a specific domain (default: all domains)
• --notes <TEXT>: Add a note to the bypass rule
• -y, --yes: Skip the confirmation prompt

Examples:

# Bypass for an IP
vercel firewall system-bypass add 10.0.0.1 --yes
 
# Bypass for a CIDR range
vercel firewall system-bypass add 10.0.0.0/24 --yes
 
# Bypass scoped to a domain
vercel firewall system-bypass add 10.0.0.1 --domain example.com --yes
 
# Bypass with wildcard domain
vercel firewall system-bypass add 10.0.0.1 --domain "*.example.com" --yes

Remove a system bypass rule so the IP is no longer exempt from system-level mitigations. Takes effect immediately without publishing.

vercel firewall system-bypass remove <ip> [options]

Options:

• --domain <DOMAIN>: Scope the removal to a specific domain
• -y, --yes: Skip the confirmation prompt

Attack Mode adds protection during targeted attacks: visitors must complete a security challenge before accessing your site, while known legitimate bots (for example search crawlers and many webhook providers) are allowed through without a challenge. These commands take effect immediately without publishing.

Enable Attack Mode for your project.

vercel firewall attack-mode enable [options]

Options:

• --duration <DURATION>: How long to keep attack mode active: 1h (default), 6h, or 24h
• -y, --yes: Skip the confirmation prompt

Examples:

# Enable for 1 hour (default)
vercel firewall attack-mode enable --yes
 
# Enable for 24 hours
vercel firewall attack-mode enable --duration 24h --yes

Disable Attack Mode so visitors are no longer challenged at the edge (subject to your custom rules and other firewall layers).

vercel firewall attack-mode disable --yes

Options:

• -y, --yes: Skip the confirmation prompt

Vercel automatically mitigates DDoS attacks and filters malicious traffic. In rare cases, you may need to temporarily pause these protections for debugging, as described in Bypass System-level Mitigations. These commands take effect immediately without publishing.

Pause automatic DDoS protection and system-level traffic filtering for 24 hours. Mitigations automatically resume after 24 hours unless you run resume sooner.

vercel firewall system-mitigations pause --yes

Options:

• -y, --yes: Skip the confirmation prompt

Resume automatic DDoS protection and system-level traffic filtering.

vercel firewall system-mitigations resume --yes

Options:

• -y, --yes: Skip the confirmation prompt

When you add, edit, or remove custom rules and IP blocks, the CLI stages those updates as drafts first. Drafts do not affect production traffic until you publish them.

# Make changes (they are staged automatically)
vercel firewall rules add "Block bots" \
  --condition '{"type":"user_agent","op":"sub","value":"crawler"}' \
  --action deny --yes
 
# Review staged changes
vercel firewall diff
 
# Publish to production
vercel firewall publish --yes

To discard staged changes without publishing, run vercel firewall discard --yes.

System bypass, Attack Mode, and system mitigations take effect immediately and do not require publishing.

Use these commands to review and publish draft changes:

Review draft changes before publishing to production. Shows what was added, removed, modified, enabled, or disabled, with field-level details for modified rules.

vercel firewall diff

Options:

• --json: Output as JSON

Publish all staged firewall changes to production.

vercel firewall publish --yes

Options:

• -y, --yes: Skip the confirmation prompt

Discard all unpublished draft changes, and revert to the current production configuration.

vercel firewall discard --yes

Options:

• -y, --yes: Skip the confirmation prompt

The tables below mirror the Rule configuration reference for custom rules. Use them with the --condition and --action flags in rules add and rules edit.

Each condition specifies a type, an op (operator), and usually a value.

The --duration option makes the action persistent for the matched client. For example, a deny with --duration 30m blocks the client for 30 minutes after the first match, rather than evaluating the rule on every request.

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

• --cwd
• --debug
• --global-config
• --help
• --local-config
• --no-color
• --scope
• --token

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

• Vercel Firewall overview
• Rule configuration reference
• Custom rules
• IP blocking
• Rate limiting
• System bypass rules
• Attack Mode
• DDoS mitigation