History

Daniil Fedotov a01c6436a0 Basic check for options overlap		2016-05-26 16:50:06 -06:00
..
config	Added legal boilerplate.	2016-02-03 10:01:32 -05:00
include	Removed rabbit_cli.hrl file.	2016-02-03 10:03:50 -05:00
lib	Basic check for options overlap	2016-05-26 16:50:06 -06:00
test	Ability to specify switches in commands	2016-05-26 15:02:10 -06:00
.gitignore	Generate map of command modules.	2016-03-04 13:15:53 -05:00
DESIGN.md	Add design document	2016-03-23 12:59:04 +00:00
README.md	Document RabbitMQ version requirement from now on	2016-05-26 01:32:20 +03:00
erlang.mk	Initial commit.	2016-02-02 13:54:36 -05:00
mix.exs	Server dependency is no longer needed	2016-05-26 01:55:00 +03:00

README.md

RabbitMQ CLI Tools

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

This is still very much a work in progress right now. For production use, go with the rabbitmqctl distributed with the rabbitmq-server repo.

Supported RabbitMQ Versions

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

Building

Requirements

Building this project requires Elixir 1.2.2 or greater.

Command line tools depend on rabbitmq-common. This library is included as a dependency in the mix.exs file, though, so the mix deps.* commands in the build process below will pull it in.

Building Standalone Executables

rabbitmqctl is the only executable provided at the moment. To generate a runnable version, use the following commands:

mix deps.get
mix compile
mix escript.build

Using

`rabbitmqctl`

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

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

Testing

Assuming you have:

installed Elixir
have a local running RabbitMQ node with the rabbitmq-federation plugin enabled (for parameter management testing), e.g. make run-broker PLUGINS='rabbitmq_federation rabbitmq_management' from a server repository clone

you can simply run mix test within the project root directory.

NOTE: You may see the following message several times:

warning: variable context is unused

This is nothing to be alarmed about; we're currently using setup context functions in Mix to start a new distributed node and connect it to the RabbitMQ server. It complains because we don't actually use the context dictionary, but it's fine otherwise.

Developing

Adding a New Command

RabbitMQCtl uses Elixir's Code.eval_string/2 method to match the command-line argument to the right module. This keeps the main module a reasonable size, but it does mean that commands have to follow a certain convention. This convention is outlined in the CommandBehaviour module.

Each command module requires the following methods:

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.
flags, which returns command-specific option flags as a list of atoms.

For example, to add a new command rabbitmqctl egg_salad:

Create a new test file test/egg_salad_command_test.exs.
In your new test file, define a module EggSaladCommandTest that runs tests against a function EggSaladCommand.run.
Create a new source file test/egg_salad_command.exs.
In your new source file, define a module EggSaladCommand that implements the run/2 function, the flags/0 function and the usage/0 function.

See src/status_command.ex and test/status_command_test.exs for simple examples of this format.

License

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