queue/cli

@lilith/queue-cli

CLI tools for managing BullMQ queues from the command line.

Features

• Queue Status: View job counts by state
• Job Listing: List jobs with filtering and limiting
• Job Clearing: Remove jobs by state or filter
• Queue Control: Pause, resume, and drain queues
• Programmatic API: Use as a library in your code

Installation

pnpm add @lilith/queue-cli

Or globally:

pnpm add -g @lilith/queue-cli

CLI Commands

queue-status

Display job counts for a queue:

queue-status <queue-name> [options]

Options:
  -r, --redis <url>  Redis URL (default: REDIS_URL env or redis://localhost:6379)

Examples:
  queue-status email-queue
  queue-status image-processing -r redis://192.168.1.100:6379

Output:

Queue: email-queue

  waiting:    5
  active:     2
  completed:  1000
  failed:     3
  delayed:    10
  paused:     0
  ──────────────
  total:      1020

queue-list

List jobs in a queue:

queue-list <queue-name> [options]

Options:
  -s, --state <state>   Job state (waiting, active, completed, failed, delayed, paused)
  -l, --limit <number>  Maximum jobs to show (default: 20)
  -f, --filter <text>   Filter by name or description
  -r, --redis <url>     Redis URL

Examples:
  queue-list email-queue
  queue-list email-queue -s failed -l 50
  queue-list image-processing -f "avatar" -s completed

queue-clear

Remove jobs from a queue:

queue-clear <queue-name> [options]

Options:
  -s, --state <state>   Job state to clear (required)
  -f, --filter <text>   Only clear jobs matching filter
  -r, --redis <url>     Redis URL
  --force               Skip confirmation prompt

Examples:
  queue-clear email-queue -s failed
  queue-clear image-processing -s completed -f "old-batch"
  queue-clear notifications -s waiting --force

queue-control

Control queue state:

queue-control <queue-name> <action> [options]

Actions:
  pause   - Pause the queue (stop processing new jobs)
  resume  - Resume a paused queue
  drain   - Remove all waiting jobs
  status  - Show if queue is paused

Options:
  -r, --redis <url>  Redis URL

Examples:
  queue-control email-queue pause
  queue-control email-queue resume
  queue-control image-processing drain
  queue-control notifications status

Programmatic API

Use as a library in your code:

import { QueueClient } from '@lilith/queue-cli';

const client = new QueueClient({
  queueName: 'email-queue',
  redisUrl: 'redis://localhost:6379',
});

// Get job counts
const counts = await client.getJobCounts();
console.log(`Waiting: ${counts.waiting}, Failed: ${counts.failed}`);

// List jobs
const failedJobs = await client.getJobs(['failed'], {
  limit: 10,
  filter: 'welcome-email',
});

// Clear jobs
const { cleared, errors } = await client.clearJobs(['completed'], {
  filter: 'old-batch',
});

// Control queue
await client.pause();
const isPaused = await client.isPaused();
await client.resume();

// Drain waiting jobs
await client.drain();

// Cleanup
await client.close();

API Reference

QueueClient

class QueueClient {
  constructor(options: QueueClientOptions);

  // Get job counts by state
  getJobCounts(): Promise<JobCounts>;

  // List jobs with optional filtering
  getJobs(
    states: JobState[],
    options?: { limit?: number; filter?: string }
  ): Promise<JobInfo[]>;

  // Clear jobs by state with optional filter
  clearJobs(
    states: JobState[],
    options?: { filter?: string }
  ): Promise<{ cleared: number; errors: number }>;

  // Queue control
  pause(): Promise<void>;
  resume(): Promise<void>;
  drain(): Promise<void>;
  isPaused(): Promise<boolean>;

  // Cleanup
  close(): Promise<void>;
}

Types

interface QueueClientOptions {
  queueName: string;
  redisUrl?: string;  // Default: REDIS_URL env or redis://localhost:6379
}

type JobState = 'waiting' | 'active' | 'completed' | 'failed' | 'delayed' | 'paused';

interface JobCounts {
  waiting: number;
  active: number;
  completed: number;
  failed: number;
  delayed: number;
  paused: number;
  total: number;
}

interface JobInfo {
  id: string;
  name: string;
  state: JobState;
  timestamp: number;
  data: Record<string, unknown>;
  failedReason?: string;
}

Environment Variables

Variable	Description	Default
REDIS_URL	Redis connection URL	redis://localhost:6379

Dependencies

• bullmq - Queue management
• ioredis - Redis client
• commander - CLI framework

License

MIT