Command line tools for RabbitMQ
Switch branches/tags
v3.7.8 v3.7.8-rc.4 v3.7.8-rc.3 v3.7.8-rc.2 v3.7.8-rc.1 v3.7.7 v3.7.7-rc.2 v3.7.7-rc.1 v3.7.7-beta.2 v3.7.7-beta.1 v3.7.6 v3.7.6-rc.2 v3.7.6-rc.1 v3.7.5 v3.7.5-rc.1 v3.7.5-beta.3 v3.7.5-beta.2 v3.7.5-beta.1 v3.7.4 v3.7.4-rc.4 v3.7.4-rc.3 v3.7.4-rc.2 v3.7.4-rc.1 v3.7.3 v3.7.3-rc.2 v3.7.3-rc.1 v3.7.2 v3.7.1 v3.7.1-beta.1 v3.7.0 v3.7.0-rc.2 v3.7.0-rc.1 v3.7.0-beta.20 v3.7.0-beta.19 rabbitmq_v3_7_0_milestone18 rabbitmq_v3_7_0_milestone17 rabbitmq_v3_7_0_milestone16 rabbitmq_v3_7_0_milestone15 rabbitmq_v3_7_0_milestone14 rabbitmq_v3_7_0_milestone13 rabbitmq_v3_7_0_milestone12 rabbitmq_v3_7_0_milestone11 rabbitmq_v3_7_0_milestone10 rabbitmq_v3_7_0_milestone9 rabbitmq_v3_7_0_milestone8 rabbitmq_v3_7_0_milestone7 rabbitmq_v3_6_13_rc2 rabbitmq_v3_6_13_rc1 rabbitmq_v3_6_13_milestone1 rabbitmq_v3_6_12 rabbitmq_v3_6_12_rc3 rabbitmq_v3_6_12_rc2 rabbitmq_v3_6_12_rc1 rabbitmq_v3_6_11 rabbitmq_v3_6_11_rc3 rabbitmq_v3_6_11_rc2 rabbitmq_v3_6_11_rc1 rabbitmq_v3_6_11_milestone5 rabbitmq_v3_6_11_milestone4 rabbitmq_v3_6_11_milestone3 rabbitmq_v3_6_11_milestone2 rabbitmq_v3_6_11_milestone1 rabbitmq_v3_6_10 rabbitmq_v3_6_10_rc2 rabbitmq_v3_6_10_rc1 rabbitmq_v3_6_10_milestone4 rabbitmq_v3_6_10_milestone3 rabbitmq_v3_6_10_milestone2 rabbitmq_v3_6_10_milestone1 rabbitmq_v3_6_9 rabbitmq_v3_6_8 rabbitmq_v3_6_7 rabbitmq_v3_6_7_rc3 rabbitmq_v3_6_7_rc2 rabbitmq_v3_6_7_rc1 rabbitmq_v3_6_7_milestone6 rabbitmq_v3_6_7_milestone5 rabbitmq_v3_6_7_milestone4 rabbitmq_v3_6_7_milestone2 rabbitmq_v3_6_7_milestone1
Nothing to show
Clone or download

README.md

RabbitMQ CLI Tools

This is the next generation implementation of rabbitmqctl and other RabbitMQ CLI tools.

This project first shipped with RabbitMQ 3.7.0. Please use the version of CLI tools that come with the RabbitMQ distribution version installed.

Goals

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

Supported RabbitMQ Versions

This version of CLI tools targets RabbitMQ master (future 3.7.0). Some operations (for example, the list_* ones) will not work with earlier server releases.

Building

Requirements

Building this project requires Elixir 1.4.4 or greater.

Command line tools depend on rabbitmq-common. Dependencies are being resolved by erlang.mk

Building Standalone Executables

This repo produces a rabbitmqctl executable which can be used as different tools (rabbitmq-plugins, rabbitmq-diagnostics) 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

Usage

rabbitmqctl

rabbitmqctl [-n node] [-t timeout] [-q] {command} [command options...]

See the rabbitmqctl man page for a full list of options.

Testing

See CONTRIBUTING.md.

Developing

Adding a New Command

Conventions

RabbitMQ CLI tools use module name conventions to match the command-line actions (commands) to modules. The convention is outlined in the CommandBehaviour module.

Command Module Interface

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 and opts 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 the usage output to provide additional command-specific documentation.
  • scopes: what scopes this command appears in. Scopes associate tools (e.g. rabbitmqctl, rabbitmq-diagnostics) with commands.
  • distribution: control erlang distribution. Can be :cli (default), :none or {:fun, fun}

Tutorial

We have a tutorial that demonstrates how to add a CLI command that deletes a queue.

Examples

See lib/rabbitmq/cli/ctl/commands/status_command.ex and test/status_command_test.exs for simple examples.

Copyright and License

The project is licensed under the MPL, the same license as RabbitMQ.

(c) Pivotal Software, Inc, 2016-2018.