nself queue

Inspect and manage BullMQ job queues. See queue depths, retry failed jobs, and purge dead letters without touching Redis directly.

Quick start

# List all active queues
nself queue list

# View stats for a specific queue
nself queue stats email-notifications

# Retry all failed jobs in a queue
nself queue retry-all email-notifications

Synopsis

nself queue <SUBCOMMAND> [FLAGS]

Description

nSelf uses BullMQ backed by Redis for background job processing. Plugins that need async work — sending emails, processing media, running AI inference, syncing files — push jobs into named queues. Workers pick them up, process them, and move them to completed or failed state.

nself queue gives you visibility into this layer without requiring direct Redis access. For dead-letter queue management (jobs that have exhausted retries), see alsonself dlq.

Subcommands

nself queue list

List all BullMQ queues registered in the stack, with job counts per state.

nself queue list
# QUEUE                    WAITING   ACTIVE   COMPLETED   FAILED   DELAYED
# email-notifications      0         1        14,832      3        0
# ai-inference             2         4        8,201       0        1
# media-processing         0         0        422         0        0
# file-sync                1         0        9,104       12       0

Show only queues with failures:

nself queue list --failed-only

JSON output for monitoring integrations:

nself queue list --json

nself queue stats <queue>

Show detailed statistics for a single queue: job counts, throughput, average processing time, and worker count.

nself queue stats email-notifications
# Queue:       email-notifications
# Workers:     2 active
#
# STATE        COUNT
# waiting      0
# active       1
# completed    14,832
# failed       3
# delayed      0
# paused       0
#
# THROUGHPUT (last 60m)
# processed:   142 jobs
# avg time:    1.2s
# p95 time:    4.8s
# error rate:  0.02%

View stats for the last N minutes:

nself queue stats email-notifications --window 15m

nself queue retry-all <queue>

Retry all failed jobs in a queue. Jobs are moved from the failed state back to waiting and processed by available workers.

nself queue retry-all email-notifications
# 3 failed jobs moved to waiting
# ✓ Retrying: email-notifications (3 jobs)

Retry only jobs that failed after a specific time:

nself queue retry-all email-notifications --since 2026-05-07T10:00:00Z

nself queue purge <queue>

Permanently delete all jobs in a specific state from a queue. Use to clear backlogs of failed jobs that are not worth retrying.

# Purge failed jobs
nself queue purge email-notifications --state failed

# Purge completed jobs (to reclaim Redis memory)
nself queue purge email-notifications --state completed

# Purge all states (drain the queue entirely)
nself queue purge email-notifications --all --confirm

Purge is irreversible. All purge commands require confirmation unless --confirm is passed.

Flags

Examples

Monitor queue health in a CI health check

FAILED=$(nself queue list --json | jq '[.[] | .failed] | add')
if [ "$FAILED" -gt 10 ]; then
  echo "Queue failure spike: $FAILED failed jobs"
  exit 1
fi

Drain a stuck media-processing queue

nself queue stats media-processing
nself queue retry-all media-processing
# If jobs keep failing, purge and investigate
nself queue purge media-processing --state failed --confirm

Weekly completed-job cleanup to reclaim Redis memory

for q in email-notifications ai-inference file-sync; do
  nself queue purge "$q" --state completed --confirm
done

Exit codes

• 0 — success
• 1 — queue not found or Redis connection error
• 2 — invalid arguments
• 3 — purge cancelled by user

Related

• nself dlq — dead-letter queue inspection and replay
• nself plugin — plugins that produce queue jobs
• nself alerts — set queue-depth alert thresholds