= Command Line Interface

ActiveMQ Artemis has a Command Line Interface (CLI) that can used to manage a few aspects of the broker like instance creation, basic user management, queues, etc.

There are two ways the CLI can be used:

* Bash Shell
** A traditional CLI that can be accessed by `./artemis <COMMAND> ARGUMENTS...`
* Artemis Shell
** A shell emulation that is accesssed by `./artemis` or `./artemis shell`.

All commands available through the traditional Command Line Interface (CLI) are also available through the Shell interface.

The Shell interface will reuse some information as you repeat commands, such as the user, password, and target broker URI making the repetitive use a bit simpler.

The CLI interface however could be used in your bash scripts for your own automation while the Shell session being a user interface in a terminal session.

== Getting Help

All of these commands can be accessed in the form of calling "artemis [COMMAND] [PARAMETERS]". You can get a complete list of available commands by typing:
[,console]
----
$ ./artemis help
Usage: artemis [COMMAND]
ActiveMQ Artemis Command Line
Commands:
  help           use 'help <command>' for more information
  auto-complete  Generates the auto complete script file to be used in bash or
                   zsh.
  shell          JLine3 shell helping using the CLI
  producer       Send message(s) to a broker.
  transfer       Move messages from one destination towards another destination.
  consumer       Consume messages from a queue.
  browser        Browse messages on a queue.
  mask           Mask a password and print it out.
  version        Print version information.
  perf           use 'help perf' for sub commands list
  check          use 'help check' for sub commands list
  queue          use 'help check' for sub commands list
  address        use 'help address' for sub commands list
  data           use 'help data' for sub commands list
  create         Create a new broker instance.
  upgrade        Update a broker instance to the current artemis.home, keeping
                   all the data and broker.xml. Warning: backup your instance
                   before using this command and compare the files.
----

It is also possible to use help at a specific command or sub-command for more information.
Examples:

To get a list of sub commands for data, you type `./artemis help data`, e.g.:

[,console]
----
Commands:
  recover  Recover (undelete) every message on the journal by creating a new
             output journal. Rolled back and acked messages will be sent out to
             the output as much as possible.
  print    Print data records information. WARNING: don't use while a
             production server is running.
  exp      Export all message-data using an XML that could be interpreted by
             any system.
  imp      Import all message-data using an XML that could be interpreted by
             any system.
  decode   Decode a journal's internal format into a new set of journal files.
  encode   Encode a set of journal files into an internal encoded data format.
  compact  Compact the journal of a non running server.
----

Or getting information about a particular command (e.g. `./artemis help create`).

[,console]
----
Usage: artemis create [--aio] [--allow-anonymous] [--autocreate] [--autodelete]
                      [--blocking] [--clustered] [--cygwin]
                      [--disable-persistence] [--failover-on-shutdown]
                      [--force] [--jdbc] [--mapped] [--nio]
                      [--no-amqp-acceptor] [--no-autocreate] [--no-autotune]
                      [--no-fsync] [--no-hornetq-acceptor] [--no-mqtt-acceptor]
                      [--no-stomp-acceptor] [--no-web] [--paging]
                      [--relax-jolokia] [--replicated] [--require-login]
                      [--shared-store] [--silent] [--slave]
                      [--support-advisory]
                      [--suppress-internal-management-objects]
                      [--use-client-auth] [--verbose] [--windows]
                      [--addresses=<addresses>]
                      [--cluster-password=<clusterPassword>]
                      [--cluster-user=<clusterUser>] [--data=<data>]
                      [--default-port=<defaultPort>] [--encoding=<encoding>]
                      [--etc=<etc>] [--global-max-messages=<globalMaxMessages>]
                      [--global-max-size=<globalMaxSize>] [--home=<home>]
                      [--host=<host>] [--http-host=<httpHost>]
                      [--http-port=<httpPort>] [--java-memory=<javaMemory>]
                      [--jdbc-bindings-table-name=<jdbcBindings>]
                      [--jdbc-connection-url=<jdbcURL>]
                      [--jdbc-driver-class-name=<jdbcClassName>]
                      [--jdbc-large-message-table-name=<jdbcLargeMessages>]
                      [--jdbc-lock-expiration=<jdbcLockExpiration>]
                      [--jdbc-lock-renew-period=<jdbcLockRenewPeriod>]
                      [--jdbc-message-table-name=<jdbcMessages>]
                      [--jdbc-network-timeout=<jdbcNetworkTimeout>]
                      [--jdbc-node-manager-table-name=<jdbcNodeManager>]
                      [--jdbc-page-store-table-name=<jdbcPageStore>]
                      [--journal-device-block-size=<journalDeviceBlockSize>]
                      [--journal-retention=<retentionDays>]
                      [--journal-retention-max-bytes=<retentionMaxBytes>]
                      [--max-hops=<maxHops>]
                      [--message-load-balancing=<messageLoadBalancing>]
                      [--name=<name>] [--password=<password>] [--ping=<ping>]
                      [--port-offset=<portOffset>] [--queues=<queues>]
                      [--role=<role>] [--security-manager=<securityManager>]
                      [--ssl-key=<sslKey>]
                      [--ssl-key-password=<sslKeyPassword>]
                      [--ssl-trust=<sslTrust>]
                      [--ssl-trust-password=<sslTrustPassword>]
                      [--static-cluster=<staticNode>] [--user=<user>]
                      [--java-options=<javaOptions>]... <directory>
Create a new broker instance.
      <directory>            The instance directory to hold the broker's
                               configuration and data. Path must be writable.
      --addresses=<addresses>
                             A comma separated list of addresses with the
                               option to specify a routing type, e.g.
                               --addresses myAddress1,myAddress2:anycast.
                               Routing-type default: multicast.
      --aio                  Set the journal as asyncio.
      --allow-anonymous      Allow connections from users with no security
                               credentials. Opposite of --require-login.
                               Default: input.
      --autocreate           Allow automatic creation of addresses & queues.
                               Default: true.
      --autodelete           Allow automatic deletion of addresses & queues.
                               Default: false.
      --blocking             Block producers when address becomes full.
                               Opposite of --paging. Default: false.
      --cluster-password=<clusterPassword>
                             The password to use for clustering. Default: input.
      --cluster-user=<clusterUser>
                             The user to use for clustering. Default: input.
      --clustered            Enable clustering.
      --cygwin               Force Cygwin script creation. Default: based on
                               your actual system.
      --data=<data>          Directory where ActiveMQ data are stored. Paths
                               can be absolute or relative to artemis.instance
                               directory. Default: data.
      --default-port=<defaultPort>
                             The port number to use for the main 'artemis'
                               acceptor. Default: 61616.
      --disable-persistence  Disable message persistence to the journal
      --encoding=<encoding>  The encoding that text files should use. Default:
                               UTF-8.
      --etc=<etc>            Directory where ActiveMQ configuration is located.
                               Paths can be absolute or relative to artemis.
                               instance directory. Default: etc.
      --failover-on-shutdown Whether broker shutdown will trigger failover for
                               clients using the core protocol. Valid only for
                               shared store. Default: false.
      --force                Overwrite configuration at destination directory.
      --global-max-messages=<globalMaxMessages>
                             Maximum number of messages that will be accepted
                               in memory before using address full policy mode.
                               Default: undefined.
      --global-max-size=<globalMaxSize>
                             Maximum amount of memory which message data may
                               consume. Default: half of the JVM's max memory.
      --home=<home>          Directory where ActiveMQ Artemis is installed.
      --host=<host>          Broker's host name. Default: 0.0.0.0 or input if
                               clustered).
      --http-host=<httpHost> Embedded web server's host name. Default:
                               localhost.
      --http-port=<httpPort> Embedded web server's port. Default: 8161.
      --java-memory=<javaMemory>
                             Define the -Xmx memory parameter for the broker.
                               Default: 2G.
      --java-options=<javaOptions>
                             Extra Java options to be passed to the profile.
      --jdbc                 Store message data in JDBC instead of local files.
      --jdbc-bindings-table-name=<jdbcBindings>
                             Name of the jdbc bindings table.
      --jdbc-connection-url=<jdbcURL>
                             The URL used for the database connection.
      --jdbc-driver-class-name=<jdbcClassName>
                             JDBC driver classname.
      --jdbc-large-message-table-name=<jdbcLargeMessages>
                             Name of the large messages table.
      --jdbc-lock-expiration=<jdbcLockExpiration>
                             Lock expiration (in milliseconds).
      --jdbc-lock-renew-period=<jdbcLockRenewPeriod>
                             Lock Renew Period (in milliseconds).
      --jdbc-message-table-name=<jdbcMessages>
                             Name of the jdbc messages table.
      --jdbc-network-timeout=<jdbcNetworkTimeout>
                             Network timeout (in milliseconds).
      --jdbc-node-manager-table-name=<jdbcNodeManager>
                             Name of the jdbc node manager table.
      --jdbc-page-store-table-name=<jdbcPageStore>
                             Name of the page store messages table.
      --journal-device-block-size=<journalDeviceBlockSize>
                             The block size of the journal's storage device.
                               Default: 4096.
      --journal-retention=<retentionDays>
                             Configure journal retention in days. If > 0 then
                               enable journal-retention-directory from broker.
                               xml allowing replay options.
      --journal-retention-max-bytes=<retentionMaxBytes>
                             Maximum number of bytes to keep in the retention
                               directory.
      --mapped               Set the journal as mapped.
      --max-hops=<maxHops>   Number of hops on the cluster configuration.
      --message-load-balancing=<messageLoadBalancing>
                             Message load balancing policy for cluster.
                               Default: ON_DEMAND. Valid values: ON_DEMAND,
                               STRICT, OFF, OFF_WITH_REDISTRIBUTION.
      --name=<name>          The name of the broker. Default: same as host name.
      --nio                  Set the journal as nio.
      --no-amqp-acceptor     Disable the AMQP specific acceptor.
      --no-autocreate        Disable auto creation for addresses & queues.
      --no-autotune          Disable auto tuning of the journal-buffer-timeout
                               in broker.xml.
      --no-fsync             Disable usage of fdatasync (channel.force(false)
                               from Java NIO) on the journal.
      --no-hornetq-acceptor  Disable the HornetQ specific acceptor.
      --no-mqtt-acceptor     Disable the MQTT specific acceptor.
      --no-stomp-acceptor    Disable the STOMP specific acceptor.
      --no-web               Whether to omit the web-server definition from
                               bootstrap.xml.
      --paging               Page messages to disk when address becomes full.
                               Opposite of --blocking. Default: true.
      --password=<password>  The user's password. Default: input.
      --ping=<ping>          A comma separated string to be passed on to the
                               broker config as network-check-list. The broker
                               will shutdown when all these addresses are
                               unreachable.
      --port-offset=<portOffset>
                             How much to off-set the ports of every acceptor.
      --queues=<queues>      A comma separated list of queues with the option
                               to specify a routing type, e.g. --queues
                               myQueue1,myQueue2:multicast. Routing-type
                               default: anycast.
      --relax-jolokia        Disable strict checking in jolokia-access.xml.
      --replicated           Enable broker replication.
      --require-login        Require security credentials from users for
                               connection. Opposite of --allow-anonymous.
      --role=<role>          The name for the role created. Default: amq.
      --security-manager=<securityManager>
                             Which security manager to use - jaas or basic.
                               Default: jaas.
      --shared-store         Enable broker shared store.
      --silent               Disable all the inputs, and make a best guess for
                               any required input.
      --slave                Be a slave broker. Valid for shared store or
                               replication.
      --ssl-key=<sslKey>     Embedded web server's key store path.
      --ssl-key-password=<sslKeyPassword>
                             The key store's password.
      --ssl-trust=<sslTrust> The trust store path in case of client
                               authentication.
      --ssl-trust-password=<sslTrustPassword>
                             The trust store's password.
      --static-cluster=<staticNode>
                             Cluster node connectors list separated by comma, e.
                               g. "tcp://server:61616,tcp://server2:61616,tcp:
                               //server3:61616".
      --support-advisory     Support advisory messages for the OpenWire
                               protocol.
      --suppress-internal-management-objects
                             Do not register any advisory addresses/queues for
                               the OpenWire protocol with the broker's
                               management service.
      --use-client-auth      Require client certificate authentication when
                               connecting to the embedded web server.
      --user=<user>          The username. Default: input.
      --verbose              Print additional information.
      --windows              Force Windows script creation. Default: based on
                               your actual system.
----

== Bash and ZSH auto complete

Bash and ZSH provide ways to auto-complete command line interfaces. To integrate with that functionality you have the option to generate the 'auto-complete' script:

[,console]
----
$ ./artemis auto-complete
----

This will generate a file named auto-complete-artemis.sh that should be used with:

[,console]
----
$ source ./auto-complete-artemis.sh
----

After the auto completion installed in the bash session, bash would start to show auto-completion information upon the pressure of the key [TAB]:

[,console]
----
$ ./artemis
activation     browser        create         kill           perf-journal   run            transfer       version
address        check          data           mask           producer       shell          upgrade
auto-complete  consumer       help           perf           queue          stop           user
----

Same showing options:

----
$ ./artemis create --
--addresses                             --jdbc-bindings-table-name              --paging
--aio                                   --jdbc-connection-url                   --password
--allow-anonymous                       --jdbc-driver-class-name                --ping
--autocreate                            --jdbc-large-message-table-name         --port-offset
--autodelete                            --jdbc-lock-expiration                  --queues
--blocking                              --jdbc-lock-renew-period                --relax-jolokia
--cluster-password                      --jdbc-message-table-name               --replicated
--cluster-user                          --jdbc-network-timeout                  --require-login
--clustered                             --jdbc-node-manager-table-name          --role
----

== Input required

Some functionality on the CLI may require user input if not provided through a parameter in cases like connecting to a broker or creating the broker instance.

For example:

[,console]
----
$ ./artemis queue stat
Connection brokerURL = tcp://localhost:61616
Connection failed::AMQ229031: Unable to validate user from /127.0.0.1:56320. Username: null; SSL certificate subject DN: unavailable

--user:
Type the username for a retry
a

--password: is mandatory with this configuration:
Type the password for a retry
----

== Artemis Shell

To initialize the shell session, type './artemis shell' (or just ./artemis if you prefer):

[,console]
----
$ ./artemis
----

The ActiveMQ Artemis Shell provides an interface that can be used to call the CLI commands directly without leaving the Java Virtual Machine.

[,console]
----
     _        _               _
    / \  ____| |_  ___ __  __(_) _____
   / _ \|  _ \ __|/ _ \  \/  | |/  __/
  / ___ \ | \/ |_/  __/ |\/| | |\___ \
 /_/   \_\|   \__\____|_|  |_|_|/___ /
 Apache ActiveMQ Artemis


For a list of commands, type help or press <TAB>:
Type exit or press <CTRL-D> to leave the session:
Apache ActiveMQ Artemis >
----

=== Connecting

It is possible to authenticate your CLI client once to the server, and reuse the connection information for future commands being performed:

[,console]
----
Apache ActiveMQ Artemis > connect --user=a --password=b --url tcp://localhost:61616
Connection brokerURL = tcp://localhost:61616
Connection Successful!
----
Now any command requiring authentication will reuse these parameters.

For example the sub-command 'queue stat' will reuse previous information to perform its connection to the broker.

[,console]
----
Apache ActiveMQ Artemis > queue stat
Connection brokerURL = tcp://localhost:61616
|NAME                     |ADDRESS                  |CONSUMER_COUNT|MESSAGE_COUNT|MESSAGES_ADDED|DELIVERING_COUNT|MESSAGES_ACKED|SCHEDULED_COUNT|ROUTING_TYPE|
|DLQ                      |DLQ                      |0             |0            |0             |0               |0             |0              |ANYCAST     |
|ExpiryQueue              |ExpiryQueue              |0             |0            |0             |0               |0             |0              |ANYCAST     |
|Order                    |Order                    |0             |4347         |4347          |0               |0             |0              |ANYCAST     |
|activemq.management.0b...|activemq.management.0b...|1             |0            |0             |0               |0             |0              |MULTICAST   |
----

==== Connecting from Command Line

To make the initial connection simpler, it is possible to start the shell with an initial connection from the startup:

[,console]
----
$ ./artemis shell --user <username> --password <password> --url <tcp://myserver:myport>
----

The CLI should not ask for an user/password for any further commands with this option being used:

Example:

[,console]
----
$ ./artemis shell --user a --password b
...


Apache ActiveMQ Artemis > queue stat
Connection brokerURL = tcp://localhost:61616
|NAME                     |ADDRESS                  |CONSUMER_COUNT|MESSAGE_COUNT|MESSAGES_ADDED|DELIVERING_COUNT|MESSAGES_ACKED|SCHEDULED_COUNT|ROUTING_TYPE|
|DLQ                      |DLQ                      |0             |0            |0             |0               |0             |0              |ANYCAST     |
|ExpiryQueue              |ExpiryQueue              |0             |0            |0             |0               |0             |0              |ANYCAST     |
|TEST                     |TEST                     |0             |8743         |8743          |0               |0             |0              |ANYCAST     |
|activemq.management.2a...|activemq.management.2a...|1             |0            |0             |0               |0             |0              |MULTICAST   |
----