RabbitMQ CLI Tools

RabbitMQ ships with a set of command-line tools for managing, inspecting, and controlling the broker without touching the Management UI. These tools are essential for scripting, automation, and server environments where a browser is not available.

The Three Main CLI Tools

rabbitmqctl    – Main management tool (users, vhosts, queues, status)
rabbitmq-plugins – Enable/disable plugins
rabbitmq-diagnostics – Health checks and diagnostics

rabbitmqctl

rabbitmqctl is the primary CLI tool. It communicates with the running RabbitMQ node using Erlang's distribution protocol. Run it as the same OS user that runs RabbitMQ (usually rabbitmq on Linux).

Checking Node Status

rabbitmqctl status

Prints node name, Erlang version, uptime, memory usage, disk alarms, and a list of enabled applications.

Stopping and Starting

rabbitmqctl stop_app    # stop only the RabbitMQ application (not Erlang)
rabbitmqctl start_app   # start the RabbitMQ application again
rabbitmqctl stop        # stop the entire Erlang node (full shutdown)

User Management

rabbitmqctl add_user alice Password123
rabbitmqctl change_password alice NewPassword456
rabbitmqctl delete_user alice
rabbitmqctl set_user_tags alice administrator
rabbitmqctl list_users

Virtual Host Management

rabbitmqctl add_vhost /myapp
rabbitmqctl delete_vhost /myapp
rabbitmqctl list_vhosts

Permission Management

rabbitmqctl set_permissions -p /myapp alice ".*" ".*" ".*"
rabbitmqctl clear_permissions -p /myapp alice
rabbitmqctl list_permissions -p /myapp
rabbitmqctl list_user_permissions alice

Queue Operations

# List all queues with message counts
rabbitmqctl list_queues name messages consumers

# List queues in a specific vhost
rabbitmqctl list_queues -p /production name messages

# Purge a queue (delete all messages, keep the queue)
rabbitmqctl purge_queue order-queue

# Delete a queue
rabbitmqctl delete_queue order-queue

Exchange Operations

rabbitmqctl list_exchanges
rabbitmqctl list_exchanges -p /production name type durable

Binding Operations

rabbitmqctl list_bindings
rabbitmqctl list_bindings -p /production

Connection and Channel Listing

rabbitmqctl list_connections
rabbitmqctl list_channels

Resetting the Node

rabbitmqctl stop_app
rabbitmqctl reset         # wipes all data: queues, exchanges, users (except default)
rabbitmqctl start_app

Use reset with extreme caution — it permanently deletes everything on the node.

rabbitmq-plugins

rabbitmq-plugins enables or disables plugins. Changes take effect immediately for most plugins on RabbitMQ 3.8+.

# Enable the Management UI
rabbitmq-plugins enable rabbitmq_management

# Enable Prometheus metrics
rabbitmq-plugins enable rabbitmq_prometheus

# List all plugins and their status (enabled/disabled)
rabbitmq-plugins list

# Disable a plugin
rabbitmq-plugins disable rabbitmq_shovel

The list output shows plugins with [E*] for explicitly enabled, [e*] for enabled as a dependency, and [ ] for disabled.

rabbitmq-diagnostics

rabbitmq-diagnostics is the health-check and troubleshooting tool. It is safer to run than rabbitmqctl status in environments where you want to avoid triggering any side effects.

# Basic ping — is the node alive?
rabbitmq-diagnostics ping

# Full health check
rabbitmq-diagnostics check_running

# Check if all alarms are cleared
rabbitmq-diagnostics check_alarms

# Check if enough ports are listening
rabbitmq-diagnostics check_port_connectivity

# Full status report
rabbitmq-diagnostics status

# Memory breakdown
rabbitmq-diagnostics memory_breakdown

# List all listeners (ports and protocols)
rabbitmq-diagnostics listeners

Output Formatting

Most rabbitmqctl list commands support a --formatter option to change output format:

rabbitmqctl list_queues --formatter=json
rabbitmqctl list_queues --formatter=csv
rabbitmqctl list_queues --formatter=table  # default, human-readable

JSON output is useful for scripting — pipe it to jq for querying:

rabbitmqctl list_queues name messages --formatter=json | jq '.[] | select(.messages > 100)'

Connecting to a Remote Node

By default, CLI tools connect to the local RabbitMQ node. To target a remote node:

rabbitmqctl -n rabbit@remote-server list_queues

The -n flag specifies the Erlang node name. The remote node must be reachable via Erlang distribution (port 25672 and the same Erlang cookie).

The Erlang Cookie

CLI tools authenticate to the RabbitMQ node using an Erlang cookie — a shared secret stored in ~/.erlang.cookie or /var/lib/rabbitmq/.erlang.cookie. If you see "connection refused" or authentication errors when running CLI commands, check that the cookie file is readable and matches on both the CLI machine and the RabbitMQ node.

Summary

rabbitmqctl handles all day-to-day management: users, vhosts, permissions, queues, exchanges, and node control. rabbitmq-plugins enables and disables plugins. rabbitmq-diagnostics provides health checks and troubleshooting without side effects. Use JSON output format for scripting. Target remote nodes with the -n flag. Ensure the Erlang cookie matches when running CLI commands from a different machine.