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 (default 10 attempts with exponential backoff). 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 name (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 prod

# With IRONFLOW_ENV set
IRONFLOW_ENV=prod ironflow outbox dlq list

# Structured output for scripting
ironflow outbox dlq list --env 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 name (required unless IRONFLOW_ENV is set)
--server	-s	string		Server URL override

Examples:

ironflow outbox dlq requeue evt_abc123 --env prod

# Bulk requeue from a list output
ironflow outbox dlq list --env prod --json \
  | jq -r '.items[].event_id' \
  | while read id; do ironflow outbox dlq requeue "$id" --env 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. 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 name (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 prod            # prompts y/N
ironflow outbox dlq discard evt_abc123 --env prod --yes      # non-interactive

---