Polyfence CLI

Command-line interface for managing Polyfence geofencing zones.

📖 Full Documentation: See Developer Guide for complete usage guide, examples, and troubleshooting.

🧪 Testing Guide: See TESTING.md for step-by-step testing instructions.

Installation

npm install -g polyfence-cli

Or run directly with npx:

npx polyfence-cli

Quick Start

1. Login with your API key:

polyfence login --api-key pd_your_api_key_here

2. List your zones:

polyfence list

3. Create a new zone:

polyfence create \
  --name "Office Zone" \
  --type circle \
  --lat 51.5074 \
  --lng -0.1278 \
  --radius 500 \
  --country UK \
  --region London

Commands

polyfence login

Save your API key for future commands.

Options:

• -k, --api-key <key> - Your Polyfence API key
• -u, --url <url> - API base URL (default: https://polyfence.io/api)

Example:

polyfence login --api-key pf_abc123...

polyfence list (alias: ls)

List all your zones.

Options:

• -c, --country <country> - Filter by country
• -r, --region <region> - Filter by region
• -t, --type <type> - Filter by type (circle, polygon)
• -a, --active - Show only active zones
• --json - Output as JSON

Examples:

# List all zones
polyfence list

# List only circle zones in UK
polyfence list --country UK --type circle

# Export as JSON
polyfence list --json > zones.json

polyfence get <zone-id>

Get details for a specific zone.

Options:

• --json - Output as JSON

Example:

polyfence get 550e8400-e29b-41d4-a716-446655440000

polyfence create

Create a new zone.

Options:

• -n, --name <name> - Zone name (required)
• -t, --type <type> - Zone type: circle or polygon (required)
• --lat <latitude> - Center latitude (for circle zones)
• --lng <longitude> - Center longitude (for circle zones)
• --radius <meters> - Radius in meters (for circle zones)
• --polygon <coordinates> - Polygon coordinates as JSON array
• -f, --file <path> - Load zone data from YAML/JSON file
• --country <code> - Country code (default: UK)
• --region <name> - Region name
• --inactive - Create zone as inactive

Examples:

Create a circle zone:

polyfence create \
  --name "London Office" \
  --type circle \
  --lat 51.5074 \
  --lng -0.1278 \
  --radius 500 \
  --country UK \
  --region London

Create a polygon zone:

polyfence create \
  --name "Campus" \
  --type polygon \
  --polygon '[[[-0.1, 51.5], [-0.1, 51.6], [0.0, 51.6], [0.0, 51.5], [-0.1, 51.5]]]' \
  --country UK

Create from file:

polyfence create --file zone.yaml

Example zone.yaml:

name: "Office Zone"
type: "circle"
center_lat: 51.5074
center_lng: -0.1278
radius_meters: 500
country: "UK"
region: "London"
is_active: true

polyfence delete <zone-id> (alias: rm)

Delete a zone by ID.

Options:

• -f, --force - Skip confirmation prompt

Examples:

# Delete with confirmation
polyfence delete 550e8400-e29b-41d4-a716-446655440000

# Delete without confirmation
polyfence delete 550e8400-e29b-41d4-a716-446655440000 --force

polyfence export

Export all zones to a file.

Options:

• -o, --output <path> - Output file path (default: zones.yaml)
• --format <format> - Output format: yaml or json (default: yaml)

Examples:

# Export to YAML
polyfence export

# Export to JSON
polyfence export --output zones.json --format json

polyfence sync <file>

Sync zones from a YAML/JSON file.

Options:

• --dry-run - Show what would be done without making changes
• --delete - Delete zones not in the file

Examples:

# Preview changes
polyfence sync zones.yaml --dry-run

# Sync zones (create new, skip existing)
polyfence sync zones.yaml

# Sync and delete zones not in file
polyfence sync zones.yaml --delete

Configuration

Configuration is stored in:

• macOS/Linux: ~/.config/polyfence-cli/config.json
• Windows: %APPDATA%\polyfence-cli\config.json

The config file stores:

• API key
• Base URL

Authentication

Get your API key from the Polyfence dashboard:

1. Go to https://polyfence.io/dashboard
2. Click "Create API Key"
3. Copy the key (starts with pf_)
4. Run polyfence login --api-key pf_your_key

Examples

Complete workflow:

# Login
polyfence login --api-key pf_abc123...

# List zones
polyfence list

# Create a zone
polyfence create --name "Office" --type circle --lat 51.5 --lng -0.1 --radius 500

# Export all zones
polyfence export --output my-zones.yaml

# Edit the file...

# Sync changes back
polyfence sync my-zones.yaml --dry-run
polyfence sync my-zones.yaml

# Delete a zone
polyfence delete <zone-id> --force

Troubleshooting

"Error: API key not configured"

• Run polyfence login --api-key YOUR_KEY

"Error: Unauthorized"

• Your API key may be invalid or revoked
• Generate a new key from the dashboard

"Error: Zone not found"

• The zone ID doesn't exist or you don't have permission to access it

Additional Resources

• Developer Guide - Complete usage guide
• API Documentation - API reference
• Developer Guide - Overview of developer tools
• Testing Guide - Step-by-step testing instructions

Support

• Documentation: https://polyfence.io/docs
• GitHub Issues: https://github.com/polyfence/cli/issues
• Email: [email protected]

Last Updated: 2025-12-24