rabbitmq-server/deps/rabbitmq_cli

RabbitMQ CLI Tools

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

This project is a work in progress and targets RabbitMQ 3.7.0 (currently the master branch). For production use, go with the rabbitmqctl distributed with the RabbitMQ version you use.

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.

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-2017.