Skip to content

Commands Overview

Jump to bottom
Griffen Fargo edited this page May 7, 2026 · 7 revisions

Commands Overview

Vercel Doorman provides a comprehensive set of CLI commands for managing firewall rules across providers.

Core Commands

list — Display Firewall Rules

List current active rules or a specific version.

# List current active rules
npx vercel-doorman list

# List rules from a specific version
npx vercel-doorman list 1

# List specific version in JSON format
npx vercel-doorman list 2 --format json

# Provider-specific
npx vercel-doorman list --provider cloudflare --verbose

sync — Deploy Configuration

Synchronize your local configuration with the remote provider.

# Auto-detect provider
npx vercel-doorman sync

# With explicit token
npx vercel-doorman sync --token YOUR_TOKEN

# Provider-specific
npx vercel-doorman sync --provider cloudflare
npx vercel-doorman sync --provider vercel --config production.config.json

Options:

  • --config, -c — Path to config file
  • --projectId, -p — Vercel Project ID
  • --teamId, -t — Vercel Team ID
  • --token — Vercel API token
  • --provider — Target provider (vercel or cloudflare)

download — Import Remote Configuration

Download firewall rules from your provider to a local config file.

# Preview changes without modifying config
npx vercel-doorman download --dry-run

# Download and update config
npx vercel-doorman download

# Download specific version
npx vercel-doorman download 1

# Provider-specific
npx vercel-doorman download --provider cloudflare

Options:

  • configVersion — Optional version number
  • --dry-run, -d — Preview changes
  • --config, -c — Path to config file
  • --token — API token
  • --provider — Target provider

validate — Validate Configuration

Check your configuration file for errors.

npx vercel-doorman validate

# Show detailed validation results
npx vercel-doorman validate --verbose

# Provider-specific validation
npx vercel-doorman validate --provider cloudflare --strict

Options:

  • --config, -c — Path to config file
  • --verbose, -v — Show detailed results

add — Create Rules from CLI

Add new firewall rules directly from the command line without manually editing .doorman.json.

# Interactive mode (guided prompts)
npx vercel-doorman add --interactive

# Inline mode (single command)
npx vercel-doorman add --name "Block Admin" --field path --op pre --value "/admin" --action deny

# Add IP blocking rule
npx vercel-doorman add ip --ip 192.168.1.100/32 --notes "Blocked for abuse"

# Rate limiting
npx vercel-doorman add --name "Rate Limit API" --field path --op pre --value "/api" --action rate_limit --requests 100 --window 60s

# Preview without writing
npx vercel-doorman add --name "Test Rule" --field path --op eq --value "/test" --action deny --dry-run

Options:

  • type — Rule type: rule (default) or ip
  • --interactive, -i — Guided prompts for rule creation
  • --name, -n — Rule name (required for inline mode)
  • --description — Rule description
  • --field — Condition field type (path, method, user_agent, ip_address, etc.)
  • --op — Operator (eq, pre, suf, sub, inc, re, ex, nex)
  • --value — Match value (comma-separated for arrays with inc operator)
  • --key — Header/query/cookie key (required for those types)
  • --neg — Negate the condition
  • --action, -a — Action type (deny, challenge, rate_limit, redirect, log, bypass)
  • --active — Enable rule immediately (default: true)
  • --requests — Rate limit: max requests
  • --window — Rate limit: time window (e.g., 60s, 5m)
  • --duration — Action duration (e.g., 1h, permanent)
  • --location — Redirect URL
  • --permanent — Use 301 redirect instead of 302
  • --ip — IP address or CIDR (for IP rules)
  • --hostname — Hostname for IP rules (default: *)
  • --notes — Notes for IP rules
  • --config, -c — Config file path
  • --dry-run, -d — Preview without writing

Features:

  • Auto-generates rule IDs from names (e.g., "Block Admin" → rule_block_admin)
  • Validates rules against the schema before saving
  • Detects duplicate rule names and warns
  • Supports all condition types, operators, and actions

template — Add Rule Templates

Add predefined rule templates to your configuration.

# List available templates
npx vercel-doorman template

# Add specific template
npx vercel-doorman template wordpress
npx vercel-doorman template ai-bots
npx vercel-doorman template bad-bots
npx vercel-doorman template block-ofac-sanctioned-countries

Available Templates:

  • bad-bots — Block common malicious bot traffic
  • ai-bots — Block AI crawlers and scrapers
  • wordpress — Block WordPress-related URLs
  • block-ofac-sanctioned-countries — OFAC compliance

Advanced Commands

init — Initialize New Project

# Interactive setup
npx vercel-doorman init --interactive

# With template
npx vercel-doorman init security-focused

# Cloudflare project
npx vercel-doorman init --provider cloudflare --interactive

Templates: empty, basic, security-focused

status — Quick Health Check

npx vercel-doorman status
npx vercel-doorman status --provider cloudflare

Shows sync status, connection health, configuration health score, and pending changes.

diff — Detailed Change Analysis

# Show differences between local and remote
npx vercel-doorman diff

# JSON output for CI/CD
npx vercel-doorman diff --format json

# Cross-provider comparison
npx vercel-doorman diff --source vercel --target cloudflare

watch — Continuous Sync

npx vercel-doorman watch
npx vercel-doorman watch --interval 2000
npx vercel-doorman watch --provider cloudflare

Watches your config file for changes and automatically syncs.

backup — Configuration Backup & Restore

# Create backup
npx vercel-doorman backup

# List backups
npx vercel-doorman backup --list

# Restore from backup
npx vercel-doorman backup --restore backup-file.json

export — Multi-Format Export

npx vercel-doorman export --format json
npx vercel-doorman export --format yaml
npx vercel-doorman export --format terraform
npx vercel-doorman export --format markdown

setup — Show Setup Guide

npx vercel-doorman setup

Displays an interactive setup guide for new users.

Global Options

These options are available on most commands:

  • --config, -c — Path to configuration file
  • --provider — Target provider (vercel or cloudflare)
  • --token — API token
  • --verbose, -v — Verbose output
  • --help — Show help

Environment Variables

Instead of passing command-line arguments, set these environment variables:

Variable Description
VERCEL_TOKEN Vercel API token
VERCEL_PROJECT_ID Vercel project ID
VERCEL_TEAM_ID Vercel team ID
CLOUDFLARE_API_TOKEN Cloudflare API token
CLOUDFLARE_ZONE_ID Cloudflare zone ID
CLOUDFLARE_ACCOUNT_ID Cloudflare account ID
DOORMAN_PROVIDER Default provider

Workflows

Development Workflow

# 1. Initialize project
npx vercel-doorman init security-focused

# 2. Add rules interactively
npx vercel-doorman add --interactive

# 3. Watch for changes during development
npx vercel-doorman watch

# 4. Check status periodically
npx vercel-doorman status

Production Workflow

# 1. Create backup before changes
npx vercel-doorman backup

# 2. Check what will change
npx vercel-doorman diff

# 3. Validate configuration
npx vercel-doorman validate

# 4. Apply changes
npx vercel-doorman sync

# 5. Verify sync completed
npx vercel-doorman status

CI/CD Integration

# Validate in CI
npx vercel-doorman validate --config production.config.json

# Check for changes (JSON output for parsing)
npx vercel-doorman diff --format json

# Deploy changes
npx vercel-doorman sync --config production.config.json

Related Pages

Getting Started

Configuration

Commands

Guides

Clone this wiki locally