queue/cli/README.md

# @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

```bash
pnpm add @lilith/queue-cli
```

Or globally:

```bash
pnpm add -g @lilith/queue-cli
```

## CLI Commands

### queue-status

Display job counts for a queue:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```typescript
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

```typescript
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

```typescript
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