platform-docs/technical/queue-cli.md

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)

pnpm add @lilith/queue-cli

Python

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.

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.

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.

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.

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

queue-clear -q email --failed

Pause queue during maintenance

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

Drain stuck jobs

queue-control -q seo drain

Debug job contents

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

Python API Usage

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.