# Queue CLI Tools

CLI tools for managing BullMQ queues. Available in both JavaScript and Python.

## Overview

| Language | Package | Registry |
|----------|---------|----------|
| JavaScript | `@lilith/queue-cli` | forge.nasty.sh NPM |
| Python | `lilith-queue-cli` | forge.nasty.sh PyPI |

Both packages operate on the same Redis queue structures and can be used interchangeably.

## Installation

### JavaScript (NestJS services)

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

### Python

```bash
pip install lilith-queue-cli --index-url https://forge.nasty.sh/api/packages/lilith/pypi/simple/
```

## CLI Commands

### queue-status

View queue status and job counts.

```bash
queue-status -q <queue-name>
queue-status -q analytics -r redis://custom:6379
queue-status -q email -j 5  # Show 5 recent jobs
```

### queue-list

List jobs in the queue.

```bash
queue-list -q <queue-name> -s <state>
queue-list -q seo -s waiting
queue-list -q seo -s failed -l 50
queue-list -q seo -s waiting -f "sitemap"  # Filter by name
queue-list -q seo -s waiting -v  # Verbose output
```

States: `waiting`, `active`, `completed`, `failed`, `delayed`

### queue-clear

Clear jobs from the queue.

```bash
queue-clear -q <queue-name> --<state>
queue-clear -q email --waiting
queue-clear -q email --failed --completed
queue-clear -q email --all
queue-clear -q email --waiting -f "test"  # Filter by name
queue-clear -q email --active --force     # Force clear active jobs
queue-clear -q email --waiting --dry-run  # Preview without clearing
```

### queue-control

Control queue operations.

```bash
queue-control -q <queue-name> <command>
queue-control -q analytics pause
queue-control -q analytics resume
queue-control -q analytics drain  # Remove all waiting jobs
```

## Queue Names Reference

| Service | Queue Name | npm script prefix |
|---------|------------|-------------------|
| analytics | `analytics` | `pnpm queue:*` |
| email | `email` | `pnpm queue:*` |
| seo | `seo` | `pnpm queue:*` |
| marketplace | `subscription-renewals` | `pnpm queue:*` |
| image-generator | `image-generator` | `pnpm queue:*` |

## Environment Variables

- `DATABASE_REDIS_URL`: Redis connection URL (default: `redis://localhost:6379`)

## Common Operations

### Clear all failed jobs

```bash
queue-clear -q email --failed
```

### Pause queue during maintenance

```bash
queue-control -q analytics pause
# ... do maintenance ...
queue-control -q analytics resume
```

### Drain stuck jobs

```bash
queue-control -q seo drain
```

### Debug job contents

```bash
queue-list -q image-generator -s waiting -v
```

## Python API Usage

```python
from queue_cli.client import QueueClient

client = QueueClient("analytics", redis_url="redis://localhost:6379")

# Get job counts
counts = client.get_job_counts()
print(f"Waiting: {counts.waiting}, Failed: {counts.failed}")

# List jobs
jobs = client.get_jobs(["waiting", "failed"], limit=100)
for job in jobs:
    print(f"[{job.state}] {job.name}")

# Control queue
client.pause()
client.resume()
client.drain()

# Clear jobs
cleared, errors = client.clear_jobs(["completed", "failed"])
print(f"Cleared {cleared} jobs")

client.close()
```

## Redis Key Structure

Both packages use BullMQ's standard Redis structure:

```
bull:{queue}:wait      (list)   - waiting jobs
bull:{queue}:active    (list)   - active jobs
bull:{queue}:completed (zset)   - completed jobs
bull:{queue}:failed    (zset)   - failed jobs
bull:{queue}:delayed   (zset)   - delayed jobs
bull:{queue}:{id}      (hash)   - job data
```

This means Python and JavaScript tools can operate on the same queues simultaneously without conflicts.