CLI Commands

bunqueue includes a powerful CLI for server management and job operations. The CLI works in two modes:

• Server mode: Start the bunqueue server
• Client mode: Send commands to a running server

Getting Started

Start the Server

# Start with defaults (TCP: 6789, HTTP: 6790)
bunqueue start

# Custom ports
bunqueue start --tcp-port 7000 --http-port 7001

# With persistent storage
bunqueue start --data-path ./data/production.db

# With authentication
AUTH_TOKENS=secret-token bunqueue start

Output:

bunqueue v1.6.0
TCP server listening on port 6789
HTTP server listening on port 6790
Database: ./data/bunq.db

Connect to Server

All client commands connect to a running server:

# Default connection (localhost:6789)
bunqueue stats

# Connect to remote server
bunqueue stats --host 192.168.1.100 --port 6789

# With authentication
bunqueue stats --token secret-token

---

Core Operations

Push Jobs

Add jobs to a queue for processing.

# Basic push
bunqueue push emails '{"to":"user@example.com","subject":"Welcome"}'

Output:

Job pushed successfully
ID: 1001
Queue: emails
Priority: 0

# With priority (higher = processed first)
bunqueue push emails '{"to":"vip@example.com"}' --priority 10

Output:

Job pushed successfully
ID: 1002
Queue: emails
Priority: 10

# Delayed job (process after 5 seconds)
bunqueue push notifications '{"message":"Reminder"}' --delay 5000

Output:

Job pushed successfully
ID: 1003
Queue: notifications
State: delayed
Run at: 2024-01-15T10:30:05.000Z

# With custom job ID
bunqueue push orders '{"orderId":"ORD-123"}' --job-id order-ORD-123

Pull Jobs

Retrieve jobs for processing (typically used by workers).

# Pull next job
bunqueue pull emails

Output:

{
  "id": "1001",
  "name": "default",
  "data": {"to":"user@example.com","subject":"Welcome"},
  "priority": 0,
  "attempts": 0,
  "timestamp": 1704067200000
}

# Pull with timeout (wait up to 5s for job)
bunqueue pull emails --timeout 5000

# Pull returns null if queue is empty
bunqueue pull empty-queue

Output:

No jobs available

Acknowledge Jobs

Mark jobs as completed after successful processing.

# Simple acknowledgment
bunqueue ack 1001

Output:

Job 1001 acknowledged
State: completed

# With result data
bunqueue ack 1001 --result '{"messageId":"msg-abc123","delivered":true}'

Output:

Job 1001 acknowledged
State: completed
Result: {"messageId":"msg-abc123","delivered":true}

Fail Jobs

Mark jobs as failed (will retry if attempts remaining).

# Mark as failed
bunqueue fail 1001 --error "SMTP connection timeout"

Output:

Job 1001 marked as failed
Error: SMTP connection timeout
Attempts: 1/3
Next retry: 2024-01-15T10:31:00.000Z

# Job moved to DLQ after max attempts
bunqueue fail 1001 --error "Permanent failure"

Output:

Job 1001 marked as failed
Error: Permanent failure
Attempts: 3/3
Status: Moved to DLQ

---

Job Management

Get Job Information

# Full job details
bunqueue job get 1001

Output:

{
  "id": "1001",
  "name": "send-email",
  "queue": "emails",
  "data": {"to":"user@example.com"},
  "state": "completed",
  "priority": 0,
  "attempts": 1,
  "progress": 100,
  "timestamp": 1704067200000,
  "processedOn": 1704067201000,
  "finishedOn": 1704067202000,
  "returnvalue": {"sent":true}
}

# Just the state
bunqueue job state 1001

Output:

completed

# Get the result
bunqueue job result 1001

Output:

{"sent":true,"messageId":"msg-abc123"}

Control Jobs

# Cancel a waiting/delayed job
bunqueue job cancel 1002

Output:

Job 1002 cancelled
Previous state: delayed

# Promote delayed job to waiting (process immediately)
bunqueue job promote 1003

Output:

Job 1003 promoted
Previous state: delayed
New state: waiting

# Discard a job completely
bunqueue job discard 1004

Output:

Job 1004 discarded

Update Job Properties

# Update progress (0-100)
bunqueue job progress 1001 50 --message "Processing attachments"

Output:

Job 1001 progress updated
Progress: 50%
Message: Processing attachments

# Change priority
bunqueue job priority 1001 20

Output:

Job 1001 priority updated
New priority: 20

# Add delay to existing job
bunqueue job delay 1001 60000

Output:

Job 1001 delayed
Run at: 2024-01-15T10:31:00.000Z

Job Logs

# View job logs
bunqueue job logs 1001

Output:

[2024-01-15 10:30:00] INFO  Starting email processing
[2024-01-15 10:30:01] INFO  Template loaded: welcome
[2024-01-15 10:30:02] INFO  Email sent successfully

# Add log entry
bunqueue job log 1001 "Custom checkpoint reached" --level info

Output:

Log entry added to job 1001

---

Queue Control

List Queues

bunqueue queue list

Output:

QUEUE          WAITING   ACTIVE   COMPLETED   FAILED   PAUSED
emails         125       5        10,234      23       no
notifications  50        2        5,102       5        no
reports        0         1        892         0        yes

Pause and Resume

# Pause processing (workers won't pick new jobs)
bunqueue queue pause emails

Output:

Queue 'emails' paused
Waiting jobs: 125 (will not be processed)
Active jobs: 5 (will complete)

# Resume processing
bunqueue queue resume emails

Output:

Queue 'emails' resumed
Processing will continue

View Queue Jobs

# List waiting jobs
bunqueue queue jobs emails --state waiting --limit 10

Output:

ID      NAME         PRIORITY   CREATED
1001    send-email   10         2024-01-15 10:30:00
1002    send-email   5          2024-01-15 10:30:01
1003    send-email   0          2024-01-15 10:30:02
...
Showing 10 of 125 jobs

# List failed jobs
bunqueue queue jobs emails --state failed

Clean Old Jobs

# Remove completed jobs older than 1 hour
bunqueue queue clean emails --grace 3600000 --state completed

Output:

Cleaned 1,523 jobs from 'emails'
State: completed
Older than: 1 hour

# Clean all old jobs (completed and failed)
bunqueue queue clean emails --grace 86400000

Drain and Obliterate

# Remove all waiting jobs (keep active)
bunqueue queue drain emails

Output:

Queue 'emails' drained
Removed: 125 waiting jobs
Active jobs: 5 (still processing)

# Remove everything (dangerous!)
bunqueue queue obliterate emails

Output:

⚠️  This will remove ALL data for queue 'emails'
Type 'emails' to confirm: emails
Queue 'emails' obliterated
Removed: 125 waiting, 5 active, 10,234 completed, 23 failed

---

DLQ Operations

View Dead Letter Queue

bunqueue dlq list emails

Output:

ID     JOB_ID   ERROR                        FAILED_AT            ATTEMPTS
1      1001     SMTP timeout                 2024-01-15 10:30:00  3
2      1005     Invalid recipient            2024-01-15 10:31:00  3
3      1008     Rate limit exceeded          2024-01-15 10:32:00  3

Total: 3 entries

Retry DLQ Jobs

# Retry all DLQ jobs
bunqueue dlq retry emails

Output:

Retrying 3 jobs from DLQ
Jobs moved back to 'emails' queue

# Retry specific job
bunqueue dlq retry emails --id 1001

Output:

Job 1001 moved from DLQ to 'emails' queue

Purge DLQ

bunqueue dlq purge emails

Output:

⚠️  This will permanently delete all DLQ entries for 'emails'
Type 'purge' to confirm: purge
Purged 3 entries from DLQ

---

Cron Jobs

List Scheduled Jobs

bunqueue cron list

Output:

NAME              QUEUE      SCHEDULE        NEXT RUN              EXECUTIONS
daily-report      reports    0 6 * * *       2024-01-16 06:00:00   45
hourly-cleanup    cleanup    0 * * * *       2024-01-15 11:00:00   1,082
health-check      health     */5 * * * *     2024-01-15 10:35:00   8,640

Add Cron Job

# Using cron expression (daily at 6 AM)
bunqueue cron add daily-report \
  -q reports \
  -d '{"type":"daily","format":"pdf"}' \
  -s "0 6 * * *"

Output:

Cron job 'daily-report' created
Queue: reports
Schedule: 0 6 * * * (daily at 6:00 AM)
Next run: 2024-01-16 06:00:00

# Using interval (every 30 minutes)
bunqueue cron add health-check \
  -q health \
  -d '{"check":"all"}' \
  -e 1800000

Output:

Cron job 'health-check' created
Queue: health
Interval: every 30 minutes
Next run: 2024-01-15 11:00:00

Delete Cron Job

bunqueue cron delete daily-report

Output:

Cron job 'daily-report' deleted

---

Rate Limiting

Set Rate Limit

# Limit to 100 jobs per second
bunqueue rate-limit set emails 100

Output:

Rate limit set for 'emails'
Limit: 100 jobs/second

Set Concurrency Limit

# Max 10 concurrent jobs
bunqueue concurrency set emails 10

Output:

Concurrency limit set for 'emails'
Limit: 10 concurrent jobs

Clear Limits

bunqueue rate-limit clear emails
bunqueue concurrency clear emails

Output:

Rate limit cleared for 'emails'
Concurrency limit cleared for 'emails'

---

Monitoring

Server Stats

bunqueue stats

Output:

bunqueue Server Statistics
==========================
Uptime: 2d 5h 30m
Version: 1.6.0

Queues: 5
Total Jobs: 156,234
  - Waiting: 234
  - Active: 12
  - Completed: 155,800
  - Failed: 188

Database Size: 45.2 MB
WAL Size: 2.1 MB

Prometheus Metrics

bunqueue metrics

Output:

# HELP bunqueue_jobs_total Total number of jobs
# TYPE bunqueue_jobs_total counter
bunqueue_jobs_total{queue="emails",state="completed"} 155800
bunqueue_jobs_total{queue="emails",state="failed"} 188

# HELP bunqueue_job_duration_seconds Job processing duration
# TYPE bunqueue_job_duration_seconds histogram
bunqueue_job_duration_seconds_bucket{queue="emails",le="0.1"} 145000
bunqueue_job_duration_seconds_bucket{queue="emails",le="1"} 155000
...

Health Check

bunqueue health

Output:

{
  "status": "healthy",
  "uptime": 185400,
  "version": "1.6.0",
  "database": {
    "status": "ok",
    "size": 47409152,
    "wal_size": 2202880
  },
  "queues": 5,
  "jobs": {
    "active": 12,
    "waiting": 234
  }
}

---

Backup Operations

Create Backup

bunqueue backup now

Output:

Backup started...
Uploading to S3: backups/2024-01-15/bunq-103000.db
Backup completed successfully
Size: 45.2 MB
Duration: 2.3s

List Backups

bunqueue backup list

Output:

KEY                                    SIZE      CREATED
backups/2024-01-15/bunq-103000.db     45.2 MB   2024-01-15 10:30:00
backups/2024-01-14/bunq-103000.db     44.8 MB   2024-01-14 10:30:00
backups/2024-01-13/bunq-103000.db     43.2 MB   2024-01-13 10:30:00

Restore Backup

bunqueue backup restore backups/2024-01-14/bunq-103000.db

Output:

⚠️  This will overwrite the current database
Type 'restore' to confirm: restore
Downloading backup...
Restoring database...
Restore completed successfully

Backup Status

bunqueue backup status

Output:

S3 Backup Configuration
=======================
Enabled: true
Bucket: my-backups
Region: us-east-1
Interval: 6 hours
Retention: 7 backups
Last backup: 2024-01-15 10:30:00
Next backup: 2024-01-15 16:30:00

---

Global Options

Option	Short	Description	Default
--host	-H	Server hostname	localhost
--port	-p	TCP port	6789
--token	-t	Authentication token	-
--json	-	Output as JSON	false
--help	-h	Show help	-
--version	-v	Show version	-

JSON Output

All commands support JSON output for scripting:

bunqueue stats --json | jq '.jobs.waiting'

Output:

234

# Use in scripts
WAITING=$(bunqueue queue jobs emails --state waiting --json | jq 'length')
if [ "$WAITING" -gt 1000 ]; then
  echo "Warning: Queue backlog detected"
fi

---

Common Workflows

Process Jobs Manually

# 1. Pull a job
JOB=$(bunqueue pull emails --json)
JOB_ID=$(echo $JOB | jq -r '.id')

# 2. Process it (your logic here)
echo "Processing job $JOB_ID..."

# 3. Acknowledge or fail
bunqueue ack $JOB_ID --result '{"processed":true}'

Monitor Queue Health

#!/bin/bash
# monitor.sh - Alert if queue backlog grows

THRESHOLD=1000
WAITING=$(bunqueue queue jobs emails --state waiting --json | jq 'length')

if [ "$WAITING" -gt "$THRESHOLD" ]; then
  echo "ALERT: emails queue has $WAITING waiting jobs"
  # Send notification...
fi

Scheduled Maintenance

#!/bin/bash
# maintenance.sh - Daily cleanup

# Clean old completed jobs (older than 24h)
bunqueue queue clean emails --grace 86400000 --state completed
bunqueue queue clean notifications --grace 86400000 --state completed

# Purge old DLQ entries
bunqueue dlq purge emails

# Create backup
bunqueue backup now