@smithington/herald-cli

Herald CLI

Command-line interface for Herald - a lightweight event-driven system that captures PostgreSQL database changes via logical replication and delivers them as HTTP webhooks.

Quick Start

# Run Herald in dev mode (uses in-memory Redis)
npx @smithington/herald-cli --database-url postgres://localhost/mydb

# Or install globally
npm install -g @smithington/herald-cli
herald --database-url postgres://localhost/mydb

What is Herald?

Herald captures changes from your PostgreSQL database and delivers them as HTTP webhooks to your applications. Perfect for:

• Event-driven architectures
• Real-time data synchronization
• Microservices communication
• Audit logging
• Cache invalidation

Usage

herald [options]

Options

Database:

• --database-url <url> - PostgreSQL connection URL (or set $DATABASE_URL)

Configuration:

• -c, --config <path> - Path to triggers YAML file (default: triggers.yaml)

Replication:

• --setup - Create replication slot and publication
• --teardown - Remove replication slot and publication

Observability:

• -v, --verbose - Enable verbose logging
• --port <port> - HTTP server port (default: 3001)

Help:

• -h, --help - Show help message
• --version - Show version

Example

# 1. Create a triggers.yaml file
cat > triggers.yaml <<EOF
triggers:
  - name: user_created
    table: users
    operations: [INSERT]
    webhook:
      url: https://api.example.com/webhooks/user-created
      headers:
        X-API-Key: \${API_KEY}
EOF

# 2. Run Herald
export API_KEY=your-secret-key
herald --dev --database-url postgres://localhost/mydb --setup

License

Proprietary - UNLICENSED