ironflow outbox

Inspect and manage the transactional outbox (issue #487). Today the only exposed subtree is dlq — operator tooling for the dead-letter table when a publish has failed past its retry budget. See the outbox explanation for background and triage flow.

ironflow outbox <subcommand> [flags]

Subcommands:

Subcommand	Description
dlq	List, requeue, or discard rows in the outbox dead-letter table

ironflow outbox dlq list

List rows in the outbox dead-letter table for one environment, newest first. Rows land in this table after the outbox worker exhausts its retry budget: 10 failed publishes of the row’s own, with exponential backoff. A NATS outage does not normally use the budget. The exceptions are a stream leader that lost its peers, which keeps reading as healthy for 10 to 20 seconds, and a storage failure on a single NATS server, described in the outbox explanation. The underlying event row in events is unaffected — only the unpublished NATS delivery is stuck.

--env is required (or set IRONFLOW_ENV). There is no default. Silent defaulting during incident triage could hide rows in the env you actually need to inspect.

ironflow outbox dlq list [flags]

Flags:

Flag	Short	Type	Default	Description
--env		string		Environment ID (required unless IRONFLOW_ENV is set)
--limit		int	50	Max rows to return (1-500)
--offset		int	0	Row offset for pagination
--json		bool	false	Output as JSON (structured for jq-based triage)
--server	-s	string		Server URL override

Examples:

# Inspect the DLQ for prod, tab-formatted
ironflow outbox dlq list --env env_default_prod

# With IRONFLOW_ENV set
IRONFLOW_ENV=env_default_prod ironflow outbox dlq list

# Structured output for scripting
ironflow outbox dlq list --env env_default_prod --limit 100 --json | jq '.items[] | {event_id, topic, last_error}'

ironflow outbox dlq requeue

Move a dead-letter row back to the live outbox table with attempts=0 so the worker picks it up on the next tick. Use this after fixing the root cause (NATS restored, stream recreated, credentials rotated, etc.).

ironflow outbox dlq requeue <event-id> [flags]

Arguments:

Argument	Required	Description
event-id	Yes	The event_id of the dead-letter entry to requeue

Flags:

Flag	Short	Type	Default	Description
--env		string		Environment ID (required unless IRONFLOW_ENV is set)
--server	-s	string		Server URL override

Examples:

ironflow outbox dlq requeue evt_abc123 --env env_default_prod

# Bulk requeue from a list output
ironflow outbox dlq list --env env_default_prod --json \
  | jq -r '.items[].event_id' \
  | while read id; do ironflow outbox dlq requeue "$id" --env env_default_prod; done

ironflow outbox dlq discard

Permanently delete a dead-letter row. The underlying events row is not deleted — only the unpublished outbox entry. Use this when a payload is unrecoverable (oversized, poison, etc.) or when you have confirmed downstream consumers don’t need the event. An events row whose event never got a NATS sequence is lost to every projection rebuild: the discard fails each rebuild in flight in the environment that could see it, and later rebuilds run without the event (projection rebuilds). Destructive; prompts for confirmation unless --yes is passed.

ironflow outbox dlq discard <event-id> [flags]

Arguments:

Argument	Required	Description
event-id	Yes	The event_id of the dead-letter entry to discard

Flags:

Flag	Short	Type	Default	Description
--env		string		Environment ID (required unless IRONFLOW_ENV is set)
--yes		bool	false	Skip the confirmation prompt
--server	-s	string		Server URL override

Examples:

ironflow outbox dlq discard evt_abc123 --env env_default_prod            # prompts y/N
ironflow outbox dlq discard evt_abc123 --env env_default_prod --yes      # non-interactive

---