..
  This file is part of PEPSI.
  Copyright (C) 2026 Pepsi contributors

  PEPSI is free software; you can redistribute it and/or modify it under the
  terms of the GNU Affero General Public License as published by the Free
  Software Foundation; either version 3, or (at your option) any later version.

===========
pepsi-queue
===========

*Inspect and repair the ingress message queue.*

Role
====

``pepsi-queue`` is the operator's diagnostic and repair tool for the
``pepsi.ingress`` table. It connects through the shared ``[pepsi-postgres]``
section and has no configuration of its own. Started as ``root`` it continues as
the ``pepsi`` service account before connecting, so no ``sudo -u pepsi`` is
needed. Reference: :manpage:`pepsi-queue(1)`.

Features
========

* **list** — list queued messages ordered by ``ingress_id``, optionally as
  ``--json`` (``ingress_id``, ``stage``, ``status``, ``mail_from``, ``subject``,
  ``received_at``, ``state``), with ``--limit``, ``--stage`` and ``--status``
  filters.
* **delete** — permanently remove a message by ``ingress_id``.
* **set-stage** — re-assign a message to a given stage and reset its ``status`` to
  ``pending`` (its ``state`` is left unchanged) so the new stage picks it up.
* **clear-all** — bulk "unstick": reset every ``running``/``paused`` message back
  to ``pending`` (``failed``/``timeout`` are left untouched) — the recovery used
  after a crash or a stalled stage.

The mutating subcommands act immediately, are not reversible, and emit no
database notification (so they are safe to run while the pipeline is idle).

Relationship to the dispatcher
==============================

``pepsi-queue`` manipulates the same ``stage``/``status``/``state`` columns the
dispatcher acts on; ``clear-all`` complements the dispatcher's own start-up reset
of orphaned ``running`` rows. It does not start stage programs.

See also
========

:doc:`pepsi-dispatch`, :doc:`../architecture`, :manpage:`pepsi-queue(1)`,
:manpage:`pepsi.conf(5)`.