README.md
1# RabbitMQ CLI Tools
2
3[](https://travis-ci.org/rabbitmq/rabbitmq-cli)
4
5This repository contains [RabbitMQ CLI tools](https://rabbitmq.com/cli.html) ([rabbitmqctl](https://www.rabbitmq.com/man/rabbitmqctl.1.man.html) and
6others).
7
8This generation of CLI tools first shipped with RabbitMQ `3.7.0`.
9
10
11## Goals
12
13Team RabbitMQ wanted a set of tools that
14
15 * Was extensible from/with plugins
16 * Supported pluggable output formats (in particular machine-friendly ones)
17 * Had good test coverage
18 * Wasn't as coupled to the server repository
19 * Could be used as a low risk vehicle for [Elixir](https://elixir-lang.org) evaluation
20
21## Supported RabbitMQ Versions
22
23Long lived branches in this repository track the same branch in RabbitMQ core and related
24repositories. So `master` tracks `master` in rabbitmq-server, `v3.7.x` tracks branch `v3.7.x` in
25rabbitmq-server and so on.
26
27Please use the version of CLI tools that come with the RabbitMQ distribution version installed.
28
29
30## Building
31
32### Requirements
33
34Building this project requires
35
36 * Erlang/OTP 21.3 (or later)
37 * [Elixir](https://elixir-lang.org/) 1.10.0 (or later).
38
39Command line tools depend on [rabbitmq-common](https://github.com/rabbitmq/rabbitmq-common).
40Dependencies are being resolved by `erlang.mk`
41
42### Building Standalone Executables
43
44This repo produces a `rabbitmqctl` executable which can be used as different tools
45(`rabbitmq-plugins`, `rabbitmq-diagnostics`, `rabbitmq-queues`, `rabbitmq-streams`, `rabbitmq-upgrade`) by copying or symlinking it with different names.
46Depending on the name, a different set of commands will be loaded and available, including
47for `--help`.
48
49To generate the executable, run
50
51```
52make
53```
54
55## Usage
56
57### `rabbitmqctl`
58
59See `rabbitmqctl help` and [rabbitmqctl man page](https://www.rabbitmq.com/man/rabbitmqctl.1.man.html) for details.
60
61### `rabbitmq-plugins`
62
63See `rabbitmq-plugins help` and [rabbitmq-plugins man page](https://www.rabbitmq.com/man/rabbitmq-plugins.1.man.html) for details.
64
65### `rabbitmq-diagnostics`
66
67See `rabbitmq-diagnostics help` and [rabbitmq-diagnostics man page](https://www.rabbitmq.com/rabbitmq-diagnostics.8.html).
68
69
70
71
72## Testing
73
74See [CONTRIBUTING.md](CONTRIBUTING.md).
75
76
77## Developing
78
79### Adding a New Command
80
81#### Conventions
82
83RabbitMQ CLI tools use module name conventions to match the command-line
84actions (commands) to modules. The convention is outlined in the `CommandBehaviour` module.
85
86#### Command Module Interface
87
88Each command module must implement the `RabbitMQ.CLI.CommandBehaviour` behaviour,
89which includes the following functions:
90
91 * `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}`.
92
93 * `merge_defaults(args, opts)`, which is used to return updated arguments and/or options.
94
95 * `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.
96
97 * `usage`, which returns a string describing the command, its arguments and its optional flags.
98 * `banner(args, opts)`, which returns a string to be printed before the command output.
99
100There are also a number of optional callbacks:
101
102 * `switches`, which returns command specific switches.
103 * `aliases`, which returns a list of command aliases (if any).
104 * `formatter`: what output formatter should be used by default.
105 * `usage_additional`: extra values appended to the `usage` output
106 to provide additional command-specific documentation.
107 * `scopes`: what scopes this command appears in. Scopes associate
108 tools (e.g. `rabbitmqctl`, `rabbitmq-diagnostics`, `rabbitmq-queues`, `rabbitmq-streams`) with commands.
109 * `distribution`: control erlang distribution.
110 Can be `:cli` (default), `:none` or `{:fun, fun}`
111
112### Tutorial
113
114We have [a tutorial](./COMMAND_TUTORIAL.md) that demonstrates how to add a CLI
115command that deletes a queue.
116
117### Examples
118
119See `lib/rabbitmq/cli/ctl/commands/status_command.ex` and `test/status_command_test.exs` for minimalistic
120but not entirely trivial examples.
121
122
123## Copyright and License
124
125The project is [licensed under the MPL](LICENSE-MPL-RabbitMQ), the same license
126as RabbitMQ.
127
128(c) 2007-2020 VMware, Inc. or its affiliates.
129
130
){kind=link}