celers-cli

Command-line interface for managing CeleRS workers, queues, and task execution.

Overview

Status: ✅ FEATURE COMPLETE

A comprehensive CLI tool providing full-featured management for CeleRS distributed task queues. Supports multiple brokers (Redis, PostgreSQL), advanced worker management, monitoring, debugging, and operational workflows.

Installation

# Install from source
cargo install --path crates/celers-cli

# The binary is named 'celers'
celers --help

Quick Start

# Initialize configuration
celers init

# Start a worker
celers worker --broker redis://localhost:6379 --queue my_queue --concurrency 4

# Check queue status
celers status --broker redis://localhost:6379 --queue my_queue

# Run health diagnostics
celers health --broker redis://localhost:6379

# Launch interactive dashboard
celers dashboard --broker redis://localhost:6379 --queue my_queue

Core Features

Worker Management

# Start worker with configuration
celers worker --broker redis://localhost:6379 --queue my_queue --concurrency 8

# List all running workers
celers worker-mgmt list --broker redis://localhost:6379

# Show worker statistics
celers worker-mgmt stats <worker-id> --broker redis://localhost:6379

# Stop a worker (graceful)
celers worker-mgmt stop <worker-id> --graceful --broker redis://localhost:6379

# Pause/resume worker
celers worker-mgmt pause <worker-id> --broker redis://localhost:6379
celers worker-mgmt resume <worker-id> --broker redis://localhost:6379

# Drain worker (finish current tasks, accept no new ones)
celers worker-mgmt drain <worker-id> --broker redis://localhost:6379

# Stream worker logs
celers worker-mgmt logs <worker-id> --follow --level info --broker redis://localhost:6379

# Scale workers
celers worker-mgmt scale 5 --broker redis://localhost:6379

Queue Management

# List all queues (Redis)
celers queue list --broker redis://localhost:6379

# Show detailed queue statistics
celers queue stats --queue my_queue --broker redis://localhost:6379

# Pause/resume queue processing
celers queue pause --queue my_queue --broker redis://localhost:6379
celers queue resume --queue my_queue --broker redis://localhost:6379

# Purge all tasks from queue
celers queue purge --queue my_queue --confirm --broker redis://localhost:6379

# Move tasks between queues
celers queue move --from old_queue --to new_queue --confirm --broker redis://localhost:6379

# Export/import queues
celers queue export --queue my_queue --output backup.json --broker redis://localhost:6379
celers queue import --queue my_queue --input backup.json --confirm --broker redis://localhost:6379

Task Operations

# Inspect task details
celers task inspect <task-id> --broker redis://localhost:6379 --queue my_queue

# Cancel a running task
celers task cancel <task-id> --broker redis://localhost:6379 --queue my_queue

# Retry a failed task
celers task retry <task-id> --broker redis://localhost:6379 --queue my_queue

# Show task result
celers task result <task-id> --backend redis://localhost:6379

# Show task execution logs
celers task logs <task-id> --broker redis://localhost:6379 --limit 100

# Move task to different queue
celers task requeue <task-id> --from queue1 --to queue2 --broker redis://localhost:6379

Dead Letter Queue (DLQ)

# Inspect failed tasks
celers dlq inspect --broker redis://localhost:6379 --queue my_queue --limit 20

# Clear all DLQ tasks
celers dlq clear --confirm --broker redis://localhost:6379 --queue my_queue

# Replay specific task from DLQ
celers dlq replay <task-id> --broker redis://localhost:6379 --queue my_queue

Scheduling & Beat

# List scheduled tasks
celers schedule list --broker redis://localhost:6379

# Add new scheduled task
celers schedule add my_daily_task \
  --task process_data \
  --cron "0 0 * * *" \
  --queue my_queue \
  --args '{"param": "value"}' \
  --broker redis://localhost:6379

# Pause/resume schedule
celers schedule pause my_daily_task --broker redis://localhost:6379
celers schedule resume my_daily_task --broker redis://localhost:6379

# Manually trigger scheduled task
celers schedule trigger my_daily_task --broker redis://localhost:6379

# Show execution history
celers schedule history my_daily_task --limit 50 --broker redis://localhost:6379

# Remove schedule
celers schedule remove my_daily_task --confirm --broker redis://localhost:6379

Monitoring & Metrics

# Display live metrics
celers metrics --format text

# Export metrics to file
celers metrics --format json --output metrics.json
celers metrics --format prometheus --output metrics.prom

# Filter metrics by pattern
celers metrics --pattern "task_*" --format text

# Watch mode (auto-refresh)
celers metrics --watch 5  # Refresh every 5 seconds

# Interactive dashboard (TUI)
celers dashboard --broker redis://localhost:6379 --queue my_queue --refresh 1

Auto-scaling

# Start auto-scaling service
celers autoscale start --broker redis://localhost:6379 --queue my_queue

# Check auto-scaling status
celers autoscale status --broker redis://localhost:6379

Alerting

# Start alert monitoring
celers alert start --broker redis://localhost:6379 --queue my_queue

# Test webhook notification
celers alert test --webhook-url https://hooks.example.com/alerts --message "Test alert"

Debugging & Diagnostics

# Debug task execution
celers debug task <task-id> --broker redis://localhost:6379 --queue my_queue

# Debug worker issues
celers debug worker <worker-id> --broker redis://localhost:6379

# System health check
celers health --broker redis://localhost:6379 --queue my_queue

# Automatic problem detection
celers doctor --broker redis://localhost:6379 --queue my_queue

Reporting & Analytics

# Daily execution report
celers report daily --broker redis://localhost:6379 --queue my_queue

# Weekly statistics
celers report weekly --broker redis://localhost:6379 --queue my_queue

# Analyze performance bottlenecks
celers analyze bottlenecks --broker redis://localhost:6379 --queue my_queue

# Analyze failure patterns
celers analyze failures --broker redis://localhost:6379 --queue my_queue

Database Operations

# Test database connection
celers db test-connection --url postgresql://user:pass@localhost/celers

# Run latency benchmark
celers db test-connection --url postgresql://user:pass@localhost/celers --benchmark

# Check database health
celers db health --url postgresql://user:pass@localhost/celers

# Show connection pool statistics
celers db pool-stats --url postgresql://user:pass@localhost/celers

# Apply migrations
celers db migrate --url postgresql://user:pass@localhost/celers --action apply

# Check migration status
celers db migrate --url postgresql://user:pass@localhost/celers --action status

Configuration

Generate Default Configuration

celers init --output celers.toml

Configuration File Format

# celers.toml

[broker]
type = "redis"  # or "postgres"
url = "redis://localhost:6379"
queue = "celers"
mode = "fifo"  # or "priority"

# Broker failover (optional)
failover_urls = [
    "redis://backup1:6379",
    "redis://backup2:6379"
]
failover_retry_attempts = 3
failover_timeout_secs = 5

[worker]
concurrency = 4
poll_interval_ms = 1000
max_retries = 3
default_timeout_secs = 300

# Multiple queues
queues = ["celers", "high_priority", "low_priority"]

[autoscale]
enabled = false
min_workers = 1
max_workers = 10
scale_up_threshold = 80
scale_down_threshold = 20
check_interval_secs = 60

[alerts]
enabled = false
webhook_url = "https://hooks.example.com/alerts"
check_interval_secs = 60
dlq_threshold = 100
failed_tasks_threshold = 50

Environment Variables

Configuration supports environment variable expansion:

[broker]
url = "${REDIS_URL:redis://localhost:6379}"  # Uses $REDIS_URL or default
queue = "${QUEUE_NAME}"  # Uses $QUEUE_NAME

Profile Support

Use different configurations for different environments:

# Create profile-specific configs
celers init --output celers-dev.toml
celers init --output celers-prod.toml

# Use specific profile
celers worker --config celers-prod.toml

Configuration Validation

# Validate configuration file
celers validate --config celers.toml

# Validate and test broker connection
celers validate --config celers.toml --test-connection

Shell Completion

Generate completion scripts for your shell:

# Bash
celers completions bash > /etc/bash_completion.d/celers

# Zsh
celers completions zsh > /usr/share/zsh/site-functions/_celers

# Fish
celers completions fish > ~/.config/fish/completions/celers.fish

# PowerShell
celers completions powershell > celers.ps1

# Elvish
celers completions elvish > celers.elv

Man Pages

Generate and install man pages:

# Generate man pages
celers manpages --output ./man

# Install system-wide
sudo cp ./man/celers.1 /usr/share/man/man1/
sudo mandb

# View man page
man celers

Broker Support

Redis

Full support for all features:

• FIFO and Priority queues
• Real-time monitoring
• Pub/Sub for commands
• DLQ management
• Task scheduling

celers worker --broker redis://localhost:6379 --queue my_queue

PostgreSQL

Full support for all features:

• FIFO and Priority queues
• Transaction support
• Schema migrations
• Connection pooling

celers worker --broker postgresql://user:pass@localhost/celers --queue my_queue

Advanced Usage

Multi-Queue Management

# Configure multiple queues in config file
[worker]
queues = ["high", "medium", "low"]

# Start worker processing all queues
celers worker --config celers.toml

Production Workflows

# 1. Health check before deployment
celers doctor --broker redis://prod:6379 --queue production

# 2. Drain workers for maintenance
celers worker-mgmt drain <worker-id> --broker redis://prod:6379

# 3. Export queue for backup
celers queue export --queue production --output backup-$(date +%Y%m%d).json

# 4. Monitor with auto-refresh
celers metrics --watch 10 --format text

# 5. Set up alerting
celers alert start --broker redis://prod:6379 --queue production

Automation & Scripting

The CLI returns appropriate exit codes for scripting:

#!/bin/bash
# Check if queue is healthy
if celers health --broker redis://localhost:6379 --queue my_queue; then
    echo "Queue is healthy"
else
    echo "Queue has issues"
    celers doctor --broker redis://localhost:6379 --queue my_queue
fi

Command Reference

Colored Output

The CLI uses colored output for better readability:

• 🟢 Green: Success messages
• 🟡 Yellow: Warnings
• 🔴 Red: Errors
• 🔵 Cyan: Information

Colors are automatically disabled when output is piped or in CI environments.

Exit Codes

• 0: Success
• 1: General error
• 2: Configuration error
• 3: Connection error

Contributing

See the main CeleRS repository for contribution guidelines.

See Also

• celers-core: Core types and traits
• celers-worker: Worker runtime
• celers-broker-redis: Redis broker implementation
• celers-broker-postgres: PostgreSQL broker implementation
• celers-metrics: Metrics collection and export

License

See LICENSE file in the repository root.