History

Loïc Hoguin f101e8a212 Use Erlang.mk's native Elixir support for CLI This avoids using Mix while compiling which simplifies a number of things and let us do further build improvements later on. Elixir is only enabled from within rabbitmq_cli currently. Eunit is disabled since there are only Elixir tests. Dialyzer will force-enable Elixir in order to process Elixir-compiled beam files. This commit also includes a few changes that are related: * The Erlang distribution will now be started for parallel-ct * Many unnecessary PROJECT_MOD lines have been removed * `eunit_formatters` has been removed, it provides little value * The new `maybe_flock` Erlang.mk function is used where possible * Build test deps when testing rabbitmq_cli (Mix won't do it anymore) * rabbitmq_ct_helpers now use the early plugins to have Dialyzer properly set up (cherry picked from commit `c5d150a7ef`)		2025-03-25 15:20:23 +00:00
..
config	Bump (c) line year	2025-01-01 17:54:10 -05:00
include	…
lib	Use Erlang.mk's native Elixir support for CLI	2025-03-25 15:20:23 +00:00
test	Use Erlang.mk's native Elixir support for CLI	2025-03-25 15:20:23 +00:00
.formatter.exs	initial .formatter.exs configuration file	2022-10-02 18:52:43 +01:00
.gitignore	Cleanup .gitignore files for the monorepo	2024-06-28 12:00:52 +02:00
CODE_OF_CONDUCT.md	Replace files with symlinks	2022-04-15 06:04:29 -07:00
COMMAND_TUTORIAL.md	remove repetitive words (#8981 )	2023-07-31 12:50:52 +02:00
CONTRIBUTING.md	Replace files with symlinks	2022-04-15 06:04:29 -07:00
DESIGN.md	Add inclusive aliases to ctl info keys	2022-11-11 14:44:05 -08:00
LICENSE	Replace @rabbitmq.com addresses with rabbitmq-core@groups.vmware.com	2023-06-20 15:40:13 +04:00
LICENSE-MPL-RabbitMQ	Revert drop of Exhibit B on MPL 2.0	2020-08-20 14:27:30 +03:00
Makefile	Use Erlang.mk's native Elixir support for CLI	2025-03-25 15:20:23 +00:00
README.md	make: Remove Travis-specific targets/config	2024-06-24 14:12:02 +02:00
mix.exs	Use Erlang.mk's native Elixir support for CLI	2025-03-25 15:20:23 +00:00

README.md

RabbitMQ CLI Tools

This repository contains RabbitMQ CLI tools (rabbitmqctl and others).

This generation of CLI tools first shipped with RabbitMQ 3.7.0.

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

Long lived branches in this repository track the same branch in RabbitMQ core and related repositories. So master tracks master in rabbitmq-server, v3.10.x tracks branch v3.10.x in rabbitmq-server and so on.

Please use the version of CLI tools that come with the RabbitMQ distribution version installed.

Building

Requirements

Building this project requires

Erlang/OTP 23.3 (or later)
Elixir 1.12.0 (or later).

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, rabbitmq-queues, rabbitmq-streams, 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

Usage

`rabbitmqctl`

See rabbitmqctl help and rabbitmqctl man page for details.

`rabbitmq-plugins`

See rabbitmq-plugins help and rabbitmq-plugins man page for details.

`rabbitmq-diagnostics`

See rabbitmq-diagnostics help and rabbitmq-diagnostics man page.

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, rabbitmq-queues, rabbitmq-streams) 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 minimalistic but not entirely trivial examples.

Copyright and License

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