162 lines
3.5 KiB
Markdown
162 lines
3.5 KiB
Markdown
# 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.
|