rabbitmqadmin v2: a Modern Command Line Client for the RabbitMQ HTTP API

rabbitmqadmin v2 is a major revision of rabbitmqadmin, one of the RabbitMQ CLI tools that target the HTTP API.

If you are migrating from the original rabbitqadmin, please see Breaking or Potentially Breaking Changes to learn about a few breaking change in the interface.

Getting Started

Releases

To download a binary build, see Releases.

Documentation

For usage documentation, see Usage.

Project Maturity

This version of rabbitmqadmin should be considered reasonably mature to be used.

Before migrating, please see Breaking or Potentially Breaking Changes to learn about a few breaking change in the interface.

Known Limitations

The following rabbitmqadmin v1 features are not currently implemented:

• Configuration file support
• Support for TLS client (x.509, HTTPS) certificate and private key

Usage

Exploring Available Command Groups and Sub-commands

To explore what command groups are available, use

rabbitmqadmin help

which will output a list of command groups:

Usage: rabbitmqadmin [OPTIONS] <command>

Commands:
  show          overview
  list          lists objects by type
  declare       creates or declares things
  delete        deletes objects
  purge         purges queues
  health_check  runs health checks
  close         closes connections
  rebalance     rebalances queue leaders
  definitions   operations on definitions
  export        see 'definitions export'
  import        see 'definitions import'
  publish       publish a message
  get           get message(s) from a queue
  help          Print this message or the help of the given subcommand(s)

To explore commands in a specific group, use

rabbitmqadmin {group name} help

Exploring the CLI with help, --help

To learn about what command groups and specific commands are available, run

rabbitmqadmin help

This flag can be appended to a command or subcommand to get command-specific documentation:

rabbitmqadmin declare queue --help
# => creates or declares things
# =>
# => Usage: rabbitmqadmin declare [object]
# => ...

Alternatively, the help subcommand can be given a command name. It's the equivalent of tagging on --help at the end of command name:

rabbitmqadmin declare help queue
# => creates or declares things
# =>
# => Usage: rabbitmqadmin declare [object]
# => ...

More specific examples are covered in the Examples section below.

Interactive vs. Use in Scripts

Like the original version, rabbitmqadmin v2 is first and foremost built for interactive use by humans. Many commands will output formatted tables, for example:

rabbitmqadmin show overview

will output a table that looks like this:

┌──────────────────┬───────────────────────────────────────────────────────────────────────────────────────────────────┐
│ Overview                                                                                                             │
├──────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────┤
│ key              │ value                                                                                             │
├──────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────┤
│ Product name     │ RabbitMQ                                                                                          │
├──────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────┤
│ Product version  │ 4.0.5                                                                                             │
├──────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────┤
│ RabbitMQ version │ 4.0.5                                                                                             │
├──────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────┤
│ Erlang version   │ 26.2.5.6                                                                                          │
├──────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────┤
│ Erlang details   │ Erlang/OTP 26 [erts-14.2.5.5] [source] [64-bit] [smp:10:10] [ds:10:10:10] [async-threads:1] [jit] │
└──────────────────┴───────────────────────────────────────────────────────────────────────────────────────────────────┘

As it is easy to observe, parsing such output in a script will be challenging.

For this reason, rabbitmqadmin v2 can render results in a way that would be much more friendly for scripting if the --non-interactive flag is passed. It is a global flag so it must be passed before the command and subcommand name:

rabbitmqadmin --non-interactive show overview

The output of the above command will not include any table borders and will is much easier to parse as a result:

 key
 Product name      RabbitMQ
 Product version   4.0.5
 RabbitMQ version  4.0.5
 Erlang version    26.2.5.6
 Erlang details    Erlang/OTP 26 [erts-14.2.5.5] [source] [64-bit] [smp:10:10] [ds:10:10:10] [async-threads:1] [jit]

Retrieving Basic Node Information

rabbitmqadmin show overview

will display essential node information in tabular form.

Retrieving Connection, Queue/Stream, Channel Churn Information

Helps assess connection, queue/stream, channel churn metrics in the cluster.

rabbitmqadmin show churn

Listing cluster nodes

rabbitmqadmin list nodes

Listing virtual hosts

rabbitmqadmin list vhosts

Listing users

rabbitmqadmin list users

Listing queues

rabbitmqadmin list queues

rabbitmqadmin --vhost "monitoring" list queues

Listing exchanges

rabbitmqadmin list exchanges

rabbitmqadmin --vhost "events" list exchanges

Listing bindings

rabbitmqadmin list bindings

rabbitmqadmin --vhost "events" list bindings

Create a Virtual Host

rabbitmqadmin declare vhost --name "vh-789" --default-queue-type "quorum" --description "Used to reproduce issue #789"

Delete a Virtual Host

rabbitmqadmin delete vhost --name "vh-789"

# --idempotently means that 404 Not Found responses will not be  considered errors
rabbitmqadmin delete vhost --name "vh-789" --idempotently

Declare a Queue

rabbitmqadmin --vhost "events" declare queue --name "target.quorum.queue.name" --type "quorum" --durable true

rabbitmqadmin --vhost "events" declare queue --name "target.stream.name" --type "stream" --durable true

rabbitmqadmin --vhost "events" declare queue --name "target.classic.queue.name" --type "classic" --durable false --auto-delete true

Delete a queue

rabbitmqadmin --vhost "events" delete queue --name "target.queue.name"

# --idempotently means that 404 Not Found responses will not be  considered errors
rabbitmqadmin --vhost "events" delete queue --name "target.queue.name" --idempotently

Declare an Exchange

rabbitmqadmin --vhost "events" declare exchange --name "events.all_types.topic" --type "topic" --durable true

rabbitmqadmin --vhost "events" declare exchange --name "events.all_type.uncategorized" --type "fanout" --durable true --auto-delete false

rabbitmqadmin --vhost "events" declare exchange --name "local.random.c60bda92" --type "x-local-random" --durable true

Delete an exchange

rabbitmqadmin --vhost "events" delete exchange --name "target.exchange.name"

# --idempotently means that 404 Not Found responses will not be  considered errors
rabbitmqadmin --vhost "events" delete exchange --name "target.exchange.name" --idempotently

Configuration Files

rabbitmqadmin v2 supports TOML-based configuration files stores groups of HTTP API connection settings under aliases ("node names" in original rabbitmqadmin speak).

Here is an example rabbitmqadmin v2 configuration file:

[local]
hostname = "localhost"
port = 15672
username = "lolz"
password = "lolz"
vhost = '/'

[staging]
hostname = "192.168.20.31"
port = 15672
username = "staging-2387a72329"
password = "staging-1d20cfbd9d"

[production]
hostname = "(redacted)"
port = 15671
username = "user-2ca6bae15ff6b79e92"
password = "user-92ee4c479ae604cc72"

Instead of specifying --hostname or --username on the command line to connect to a cluster (or specific node) called staging, a --node alias can be specified instead:

# will use the settings from the section called [staging]
rabbitmqadmin --node staging show churn

Default configuration file path is at $HOME/.rabbitmqadmin.conf, as it was in the original version of rabbitmqadmin. It can be overridden on the command line:

# will use the settings from the section called [staging]
rabbitmqadmin --config $HOME/.configuration/rabbitmqadmin.conf --node staging show churn

Project Goals Compared to rabbitmqadmin v1

This version of rabbitmqadmin has a few ideas in mind:

• This is a major version bump. Therefore, reasonable breaking changes are OK. rabbitmqadmin hasn't seen a revision in fourteen years
• rabbitmqadmin should be standalone binary. There are very few reasons not to build and distribute it that way
• Standalone project, not an obscure feature: rabbitmqadmin should be a standalone tool, not a relatively unknown "feature" of the RabbitMQ management plugin, and should be developed as such, not tied completely to the development environment, practices and release schedule of RabbitMQ itself
• v2 should be a distributed via GitHub releases and not a special rabbitmq_management endpoint
• There is a lot of room to improve validation of flags and arguments, since breaking changes are OK for v2
• This tool should strive to be as free as practically possible from CVEs in other projects that show up on security scans. CVEs from older Python versions should not plague OCI images that choose to include rabbitmqadmin v2

Breaking or Potentially Breaking Changes

--snake-case for Command Options

rabbitmqadmin v1 used lower_case for named command arguments, for example:

# Note: auto_delete
rabbitmqadmin-v1 --vhost "vh-2" declare queue name="qq.1" type="quorum" durable=true auto_delete=false

rabbitmqadmin v2 uses a more typical --snake-case format for the same arguments:

# Note: --auto-delete
rabbitmqadmin --vhost "vh-2" declare queue --name "qq.1" --type "quorum" --durable true --auto-delete false 

Global Arguments Come First

Global flags in rabbitmqadmin v2 must precede the command category (e.g. list) and the command itself, namely various HTTP API endpoint options and --vhost:

rabbitmqadmin --vhost "events" declare queue --name "target.quorum.queue.name" --type "quorum" --durable true

--prefix Overrides API Path Prefix

In rabbitmqadmin v1, --path-prefix appended to the default API path prefix. In this version, the value passed to --path-prefix will be used as given, in other words, it replaces the default prefix, /api.

Configuration File Format Moved to TOML

rabbitmqadmin v1 supported ini configuration files that allowed the user to group a number of command line values under a name, e.g. a cluster or node nickname.

Due to the "no dependencies other than Python" design goal of rabbitmqadmin v1, this feature was not really tested, and the specific syntax (that of ini files, supported by Python's ConfigParser) linting, parsing or generation tools were not really available.

rabbitmqadmin v2 replaces this format with TOML, a popular configuration standard with verification and linting tools, as well as very mature parser that is not at all specific to rabbitmqadmin v2.

Here is an example rabbitmqadmin v2 configuration file:

[local]
hostname = "localhost"
port = 15672
username = "lolz"
password = "lolz"
vhost = '/'

[staging]
hostname = "192.168.20.31"
port = 15672
username = "staging-2387a72329"
password = "staging-1d20cfbd9d"

[production]
hostname = "(redacted)"
port = 15671
username = "user-efe1f4d763f6"
password = "(redacted)"

Getting Help

Please use GitHub Discussions in this repository and RabbitMQ community Discord server.

License

This tool, rabbitmqadmin (v2 and later versions), is dual-licensed under the Apache Software License 2.0 and the MIT license.