# Manage Next.js Background Queues from Terminal CLI

> Monitor, retry, and discard failed background jobs from the command line or Claude Code. Zero web dashboards needed during production incidents.

Source: https://boringpush.com/blog/agent-first-cli-background-queues-nextjs

It is eleven o'clock on a Saturday evening.

You are away from your laptop, having dinner with friends, when your phone buzzes with a notification.

A third-party webhook secret expired, and twelve background jobs just failed in production.

If your queue relies on a complex web dashboard like Bull Board or an external cloud portal, you are stuck. You have to pull out a laptop, find a Wi-Fi hotspot, log into a browser dashboard, and click through UI tables.

If your queue is built CLI-first, you resolve the incident in thirty seconds from a mobile SSH terminal.

## The problem with GUI-only queue monitors

The web development industry spent the last decade building heavy browser interfaces for every internal tool.

We built admin dashboards for database rows, graphical interfaces for Redis keys, and web portals for background job queues.

These web dashboards look great in marketing product screenshots. In production emergencies, they create distinct points of friction:

First, mobile usability. Most web-based queue dashboards are designed for desktop monitors. Trying to tap tiny pagination buttons and inspect JSON stack traces on a phone screen is an exercise in frustration.

Second, authentication overhead. Accessing internal dashboards often requires logging into Google workspace, completing two-factor authentication prompts, and navigating internal VPNs.

Third, AI agent blindness. Autonomous coding agents like Claude Code, Cursor, and OpenCode operate in terminal environments. An agent cannot log into an interactive web dashboard to diagnose why a job failed.

If an operational tool cannot be controlled from the command line, it is inaccessible to modern AI workflows.

## The Agent-First philosophy: CLI as the source of truth

An agent-first architecture treats the command-line interface as a first-class citizen.

Every capability available in a graphical interface should be directly executable via deterministic terminal commands that accept flags and return structured data.

When you design your background queue CLI-first, you gain three major advantages:

1. Mobile incident management: You can SSH into your server using Termius or prompt an agent to diagnose issues directly from your phone.
2. Scriptability: You can wire queue management into automated deployment hooks, health checks, and alerting scripts.
3. AI agent empowerment: An AI assistant can inspect failed jobs, fix the underlying code bug, and replay the dead tasks without human hand-holding.

## How BoringPush manages queues from the terminal

In BoringPush, the operator CLI (`bp`) exposes the full background queue lifecycle directly to the terminal.

The command surface is simple, predictable, and self-documenting.

### 1. Inspecting queue status and counts

To see what your background workers are doing right now:

```bash
# Get high-level counts across all job states
npm run bp -- jobs counts
```

This returns clean, human-readable summaries:

```text
Pending:   4
Running:   2
Completed: 1,842
Dead:      3
```

To see the exact details of failed jobs:

```bash
npm run bp -- jobs list --status dead
```

### 2. Inspecting failure details

When an AI agent or human engineer needs to understand why a task crashed, they inspect the specific job:

```bash
npm run bp -- jobs show job_8f93a1
```

The CLI prints the exact payload, attempt counts, execution timestamps, and the complete error stack trace.

There is no need to hunt through gigabytes of raw server logs. The error is tied directly to the job record.

### 3. Recovering dead jobs with one command

Once you fix the root cause (such as updating an expired environment variable), you recover the quarantined jobs immediately:

```bash
# Replay all failed dead-letter jobs
npm run bp -- jobs retry-dead
```

The queue engine resets the retry counters and marks the tasks as pending.

The worker thread pool picks them up instantly and completes the work.

## JSON envelopes for AI agent workflows

When an autonomous AI agent operates inside your codebase, plain text tables are difficult to parse reliably.

Every command in the BoringPush CLI supports the `--json` flag:

```bash
npm run bp -- --json jobs list --status dead
```

This outputs a strict, structured JSON envelope:

```json
{
  "ok": true,
  "data": [
    {
      "id": "job_8f93a1",
      "path": "billing/send-receipt",
      "attempts": 5,
      "lastError": "Invalid Resend API Key",
      "payload": { "orderId": "ord_102" }
    }
  ],
  "exitCode": 0
}
```

An agent like Claude Code reads this JSON, identifies the missing key in `.env.production`, alerts the owner or fixes the file, and runs `bp jobs retry-dead` to complete the recovery.

The entire incident is detected, diagnosed, and resolved without opening a web browser.

## The future of software maintenance is headless

The tools we build must evolve alongside the way we write code.

When software was maintained exclusively by human engineers sitting at multi-monitor desks, graphical dashboards were a reasonable choice.

Today, engineers fix production issues from their phones while walking the dog. Tomorrow, autonomous agents will diagnose and repair background workers before a human even notices an alert.

Build your systems terminal-first. Ensure every capability has a deterministic command.

Make your background queues inspectable, recoverable, and accessible from any shell on earth.

## FAQ

### Can I run these CLI commands from outside the production server?

Yes. The `bp` CLI can run directly on the VPS via SSH, or locally by communicating with your application's authenticated admin API route using personal bearer tokens.

### How does the CLI authenticate requests?

When run locally, `bp` uses secure Bearer tokens generated from your user account. When run directly on the VPS, it interacts directly with the local queue database using process-level permissions.

### Can an AI agent accidentally delete all my queue data?

No. Prime Directive 7 in BoringPush strictly bans destructive delete operations. The CLI provides commands to retry or discard dead jobs, but historical audit records and database tables are never dropped.

### How do I stream real-time queue events in my terminal?

BoringPush includes an event tailing command: `npm run bp -- events tail --topics queue`. This streams live dispatch, completion, and failure events in real time using Server-Sent Events.

### Does running the CLI put load on my database?

No. The CLI queries are indexed on the `status` column and execute in fractions of a millisecond against local SQLite.

## Keep reading

- [Next.js Background Jobs Without Redis: $0 BullMQ](/blog/nextjs-background-jobs-no-redis-bullmq-alternative) — the full queue setup
- [Why Next.js Background Tasks Die in Production](/blog/why-nextjs-background-tasks-die-in-production) — solving serverless freezes
- [Ship Code From Your Phone with Claude Code](/blog/ship-code-from-phone) — mobile production workflows