This repository contains RabbitMQ CLI tools (rabbitmqctl and others).
This generation of CLI tools first shipped with RabbitMQ 3.7.0
.
Team RabbitMQ wanted a set of tools that
- Was extensible from/with plugins
- Supported pluggable output formats (in particular machine-friendly ones)
- Had good test coverage
- Wasn't as coupled to the server repository
- Could be used as a low risk vehicle for Elixir evaluation
Long lived branches in this repository track the same branch in RabbitMQ core and related
repositories. So master
tracks master
in rabbitmq-server, v3.7.x
tracks branch v3.7.x
in
rabbitmq-server and so on.
Please use the version of CLI tools that come with the RabbitMQ distribution version installed.
Building this project requires
- Erlang/OTP 21.3 (or later)
- Elixir 1.10.0 (or later).
Command line tools depend on rabbitmq-common.
Dependencies are being resolved by erlang.mk
This repo produces a rabbitmqctl
executable which can be used as different tools
(rabbitmq-plugins
, rabbitmq-diagnostics
, rabbitmq-queues
, rabbitmq-upgrade
) by copying or symlinking it with different names.
Depending on the name, a different set of commands will be loaded and available, including
for --help
.
To generate the executable, run
make
See rabbitmqctl help
and rabbitmqctl man page for details.
See rabbitmq-plugins help
and rabbitmq-plugins man page for details.
See rabbitmq-diagnostics help
and rabbitmq-diagnostics man page.
See CONTRIBUTING.md.
RabbitMQ CLI tools use module name conventions to match the command-line
actions (commands) to modules. The convention is outlined in the CommandBehaviour
module.
Each command module must implement the RabbitMQ.CLI.CommandBehaviour
behaviour,
which includes the following functions:
-
validate(args, opts)
, which returns either:ok
or a tuple of{:validation_failure, failure_detail}
where failure detail is typically one of::too_many_args
,:not_enough_args
or{:bad_argument, String.t}
. -
merge_defaults(args, opts)
, which is used to return updated arguments and/or options. -
run(args, opts)
, where the actual command is implemented. Here,args
is a list of command-specific parameters andopts
is a Map containing option flags. -
usage
, which returns a string describing the command, its arguments and its optional flags. -
banner(args, opts)
, which returns a string to be printed before the command output.
There are also a number of optional callbacks:
switches
, which returns command specific switches.aliases
, which returns a list of command aliases (if any).formatter
: what output formatter should be used by default.usage_additional
: extra values appended to theusage
output to provide additional command-specific documentation.scopes
: what scopes this command appears in. Scopes associate tools (e.g.rabbitmqctl
,rabbitmq-diagnostics
,rabbitmq-queues
) with commands.distribution
: control erlang distribution. Can be:cli
(default),:none
or{:fun, fun}
We have a tutorial that demonstrates how to add a CLI command that deletes a queue.
See lib/rabbitmq/cli/ctl/commands/status_command.ex
and test/status_command_test.exs
for minimalistic
but not entirely trivial examples.
The project is licensed under the MPL, the same license as RabbitMQ.
(c) 2007-2020 VMware, Inc. or its affiliates.