Commands Overview

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 @gfargo/doorman list

# List rules from a specific version
npx @gfargo/doorman list 1

# List specific version in JSON format
npx @gfargo/doorman list 2 --format json

# Provider-specific
npx @gfargo/doorman list --provider cloudflare --debug
npx @gfargo/doorman list --provider fastly

sync — Deploy Configuration

Synchronize your local configuration with the remote provider.

# Auto-detect provider
npx @gfargo/doorman sync

# With explicit token
npx @gfargo/doorman sync --token YOUR_TOKEN

# Provider-specific
npx @gfargo/doorman sync --provider cloudflare
npx @gfargo/doorman sync --provider fastly
npx @gfargo/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, cloudflare, or fastly)

download — Import Remote Configuration

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

# Preview changes without modifying config
npx @gfargo/doorman download --dry-run

# Download and update config
npx @gfargo/doorman download

# Download specific version
npx @gfargo/doorman download 1

# Provider-specific
npx @gfargo/doorman download --provider cloudflare
npx @gfargo/doorman download --provider fastly

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 @gfargo/doorman validate

# Show detailed validation results
npx @gfargo/doorman validate --verbose

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 @gfargo/doorman add --interactive

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

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

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

# Preview without writing
npx @gfargo/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

remove — Delete Rules from CLI

Remove firewall rules or IP entries by name, ID, or interactive selection. Aliases: rm, delete.

# Remove by name
npx @gfargo/doorman remove --name "Block Admin Access"

# Remove by ID
npx @gfargo/doorman remove --id rule_block_admin_access

# Remove multiple rules by ID
npx @gfargo/doorman remove --id rule_one --id rule_two

# Remove IP rule
npx @gfargo/doorman remove ip --ip 192.168.1.100/32

# Interactive selection (pick from list)
npx @gfargo/doorman remove --interactive

# Remove all disabled rules
npx @gfargo/doorman remove --disabled

# Remove all rules (requires confirmation)
npx @gfargo/doorman remove --all

# Dry run (show what would be removed)
npx @gfargo/doorman remove --name "Old Rule" --dry-run

Options:

• type — What to remove: rule (default) or ip
• --interactive, -i — Select rules to remove from a list
• --name, -n — Remove rule by name (exact match)
• --id — Remove rule by ID (supports multiple)
• --ip — Remove IP rule by IP address
• --disabled — Remove all disabled (active: false) rules
• --all — Remove all rules (requires confirmation)
• --force, -f — Skip confirmation prompt
• --config, -c — Config file path
• --dry-run, -d — Preview without writing

Features:

• Confirmation prompt before removal (skip with --force)
• Fuzzy name matching suggests alternatives when exact match fails
• Backup suggestion for bulk removal operations
• Warns when config will have empty rules after removal

template — Add Rule Templates

Add predefined rule templates to your configuration.

# Interactive: prompts you to select from the available templates
npx @gfargo/doorman template

# Add specific template
npx @gfargo/doorman template wordpress
npx @gfargo/doorman template ai-bots
npx @gfargo/doorman template bad-bots
npx @gfargo/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 @gfargo/doorman init --interactive

# With template
npx @gfargo/doorman init security-focused

init only supports Vercel today — it has no --provider flag and doesn't prompt for Cloudflare or Fastly credentials. For a Cloudflare or Fastly project, create .doorman.json manually (see Cloudflare Setup or Fastly Setup).

Templates: empty, basic, security-focused

status — Quick Health Check

npx @gfargo/doorman status
npx @gfargo/doorman status --provider cloudflare
npx @gfargo/doorman status --provider fastly

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

diff — Detailed Change Analysis

# Show differences between local and remote
npx @gfargo/doorman diff

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

# Diff against a specific provider (compares your local config to that one remote — diff doesn't do cross-provider comparison)
npx @gfargo/doorman diff --provider cloudflare
npx @gfargo/doorman diff --provider fastly

watch — Continuous Sync

npx @gfargo/doorman watch
npx @gfargo/doorman watch --interval 2000
npx @gfargo/doorman watch --provider cloudflare
npx @gfargo/doorman watch --provider fastly

Watches your config file for changes and automatically syncs.

backup — Configuration Backup & Restore

# Create backup
npx @gfargo/doorman backup

# List backups
npx @gfargo/doorman backup --list

# Restore from backup
npx @gfargo/doorman backup --restore backup-file.json

export — Multi-Format Export

npx @gfargo/doorman export --format json
npx @gfargo/doorman export --format yaml
npx @gfargo/doorman export --format terraform
npx @gfargo/doorman export --format markdown

setup — Show Setup Guide

npx @gfargo/doorman setup

Displays an interactive setup guide for new users.

Global Options

• --help — Show help (every command)
• --config, -c — Path to configuration file (every command except list and setup)
• --provider — Target provider (vercel, cloudflare, or fastly) — only on provider-aware commands: list, sync, download, status, diff, watch, backup, export
• --token — Vercel API token (same provider-aware commands as --provider, plus their Cloudflare/Fastly equivalents like --apiToken and --workspaceId)
• --verbose, -v — Detailed output — validate only

Environment Variables

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

Workflows

Development Workflow

# 1. Initialize project
npx @gfargo/doorman init security-focused

# 2. Add rules interactively
npx @gfargo/doorman add --interactive

# 3. Watch for changes during development
npx @gfargo/doorman watch

# 4. Check status periodically
npx @gfargo/doorman status

Production Workflow

# 1. Create backup before changes
npx @gfargo/doorman backup

# 2. Check what will change
npx @gfargo/doorman diff

# 3. Validate configuration
npx @gfargo/doorman validate

# 4. Apply changes
npx @gfargo/doorman sync

# 5. Verify sync completed
npx @gfargo/doorman status

CI/CD Integration

# Validate in CI
npx @gfargo/doorman validate --config production.config.json

# Check for changes (JSON output for parsing)
npx @gfargo/doorman diff --format json

# Deploy changes
npx @gfargo/doorman sync --config production.config.json

Related Pages

• Getting Started — Quick setup guide
• Configuration — Configuration file reference
• Examples — Real-world configuration examples
• Templates — Pre-built rule templates