CLI Reference

Rabbit Relay ships a CLI for reviewing topology in code review and operating dead-letter queues in production.

Connection URL

Commands that contact RabbitMQ resolve the connection URL in this order:

--url <amqp-url> flag
RABBITMQ_URL environment variable
amqp://localhost

Plan

Export the topology your broker would declare, perfect for CI:

npx rabbit-relay plan ./setup.mjs > plan.json

Works with topologyMode: "plan-only" so no setup calls touch the broker.

Flag	Description
`--output <file>`	Write plan JSON to a file instead of stdout

Validate

Check that a plan matches a live broker:

npx rabbit-relay validate plan.json --url amqp://user:pass@localhost:5672

Flag	Default	Description
`--url <url>`	`RABBITMQ_URL` or `amqp://localhost`	RabbitMQ connection URL

Exit code: 0 on valid, 1 on blocking issues.

Diff

Compare two plans (local vs production) before merging:

npx rabbit-relay diff plan.json plan.production.json

Output:

# Exchanges only in first plan (new):
+ orders.ex (topic, durable)

# Queues only in second plan (missing):
- orders.q

# Bindings only in first plan (new):
+ orders.q → orders.ex [routingKey: "orders.*"]

Plans are identical.

Dead-letter queue operations

Inspect depth, peek messages (non-destructively), or redrive them back:

npx rabbit-relay dlq inspect orders.dlq --url amqp://localhost

Queue depth and consumer status.

Output (JSON):

{ "queue": "orders.dlq", "messageCount": 42, "consumerCount": 0 }

Add --dry-run to redrive for a no-op count of what would move.

Help

npx rabbit-relay help
npx rabbit-relay dlq help

Exit codes

Code	Meaning
`0`	Success
`1`	Validation failure, missing entity, unexpected error

The dlq redrive command exits with 1 when one or more messages fail.

CI usage

A typical CI pipeline generates a plan from application code, validates it against a staging broker, and compares it with a known production plan:

# 1. Generate the topology plan from the application code
npx rabbit-relay plan ./ci/topology.mjs > plan.json

# 2. Validate against a staging RabbitMQ
npx rabbit-relay validate plan.json --url "$RABBITMQ_URL"

# 3. Compare against the production plan (generated earlier)
npx rabbit-relay diff plan.json plan.production.json

The plan command runs a setup script in plan-only mode. The script must export a default function (or named export setup) that receives a RabbitMQBroker instance:

// ci/topology.mjs
import { RabbitMQBroker } from "@bitspacerlabs/rabbit-relay";

export default function (broker) {
  broker
    .queue("orders.q")
    .exchange("orders.ex", {
      exchangeType: "topic",
      routingKey: "orders.*",
      deadLetter: {
        exchange: "orders.dlx",
        queue: "orders.dlq",
        autoDeclare: true,
      },
    });
}

Generating plans programmatically

You can also build the plan in code and write it to JSON yourself:

import { RabbitMQBroker } from "@bitspacerlabs/rabbit-relay";

const broker = new RabbitMQBroker("ci", {
  topologyMode: "plan-only",
});

await broker
  .queue("orders.q")
  .exchange("orders.ex", {
    exchangeType: "topic",
    routingKey: "orders.*",
  });

console.log(JSON.stringify(broker.planTopology(), null, 2));

Page	Description
Topology Planner	Generating topology plans
Topology Validation	Validating plans against RabbitMQ
Retry & DLQ	DLQ config and redrive

On this page