Domainarr

DNS sync CLI for managing Pi-hole and Cloudflare DNS records together.

Keep your local Pi-hole DNS entries synchronized with Cloudflare DNS, enabling split-horizon DNS where local devices resolve to internal IPs while external clients use Cloudflare.

Table of Contents

• Features
• Installation
• Quick Start
• Commands
• Configuration
• Backup & Restore
• License

Features

• Dual-provider sync: Manage DNS records in both Pi-hole and Cloudflare from a single CLI
• Pi-hole as source of truth: Sync command pushes Pi-hole records to Cloudflare
• Backup & restore: Create timestamped backups and restore when needed
• Interactive setup: domainarr init guides you through configuration
• Idempotent operations: Safe to run multiple times without duplicating records

Installation

# Clone and build
git clone https://github.com/ryanbas21/domainarr.git
cd domainarr
pnpm install
pnpm build

# Link globally (optional)
pnpm link --global

Quick Start

1. Configure your Pi-hole and Cloudflare credentials:

   domainarr init

   This creates ~/.config/domainarr/config.json with your settings.

2. Add a DNS record to both providers:

   domainarr add homelab.example.com 192.168.1.100

3. List all records with sync status:

   domainarr list

4. Sync Pi-hole to Cloudflare:

   domainarr sync

Commands

| Command | Description | |---------|-------------| | domainarr add <domain> <ip> | Add DNS record to both Pi-hole and Cloudflare | | domainarr remove <domain> | Remove DNS record from both providers | | domainarr list | List all records with sync status | | domainarr sync | Sync Pi-hole records to Cloudflare (Pi-hole is source of truth) | | domainarr backup | Create a timestamped backup | | domainarr restore [file] | Restore from a backup file | | domainarr init | Interactive setup wizard |

Configuration

Configuration is stored at ~/.config/domainarr/config.json:

{
  "pihole": {
    "url": "http://pihole.local",
    "password": "your-pihole-password"
  },
  "dnsProvider": {
    "type": "cloudflare",
    "apiToken": "your-cloudflare-api-token",
    "zoneId": "your-zone-id",
    "zone": "example.com"
  },
  "backup": {
    "path": "/path/to/backups"
  }
}

Pi-hole Setup

• Requires Pi-hole v6+ with REST API enabled
• Password is your Pi-hole web interface password

Cloudflare Setup

1. Create an API token at Cloudflare Dashboard
2. Grant Zone:DNS:Edit permissions for your zone
3. Find your Zone ID on the zone overview page

Backup & Restore

Create backups before making bulk changes:

# Create backup
domainarr backup
# Output: Backup saved to /path/to/backups/domainarr-backup-2024-01-15T10-30-00-000Z.json

# List available backups
domainarr restore
# Shows list of available backup files

# Restore from specific backup
domainarr restore domainarr-backup-2024-01-15T10-30-00-000Z.json

Backups include records from both Pi-hole and Cloudflare.

License

ISC