Skip to content

Commands Overview

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

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:

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
FASTLY_API_TOKEN Fastly API token
FASTLY_WORKSPACE_ID Fastly Next-Gen WAF workspace ID
DOORMAN_PROVIDER Default provider

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

Configuration

Commands

Guides

Clone this wiki locally