= 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 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 ' 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=] [--cluster-password=] [--cluster-user=] [--data=] [--default-port=] [--encoding=] [--etc=] [--global-max-messages=] [--global-max-size=] [--home=] [--host=] [--http-host=] [--http-port=] [--java-memory=] [--jdbc-bindings-table-name=] [--jdbc-connection-url=] [--jdbc-driver-class-name=] [--jdbc-large-message-table-name=] [--jdbc-lock-expiration=] [--jdbc-lock-renew-period=] [--jdbc-message-table-name=] [--jdbc-network-timeout=] [--jdbc-node-manager-table-name=] [--jdbc-page-store-table-name=] [--journal-device-block-size=] [--journal-retention=] [--journal-retention-max-bytes=] [--max-hops=] [--message-load-balancing=] [--name=] [--password=] [--ping=] [--port-offset=] [--queues=] [--role=] [--security-manager=] [--ssl-key=] [--ssl-key-password=] [--ssl-trust=] [--ssl-trust-password=] [--static-cluster=] [--user=] [--java-options=]... Create a new broker instance. The instance directory to hold the broker's configuration and data. Path must be writable. --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= The password to use for clustering. Default: input. --cluster-user= The user to use for clustering. Default: input. --clustered Enable clustering. --cygwin Force Cygwin script creation. Default: based on your actual system. --data= Directory where ActiveMQ data are stored. Paths can be absolute or relative to artemis.instance directory. Default: data. --default-port= The port number to use for the main 'artemis' acceptor. Default: 61616. --disable-persistence Disable message persistence to the journal --encoding= The encoding that text files should use. Default: UTF-8. --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= Maximum number of messages that will be accepted in memory before using address full policy mode. Default: undefined. --global-max-size= Maximum amount of memory which message data may consume. Default: half of the JVM's max memory. --home= Directory where ActiveMQ Artemis is installed. --host= Broker's host name. Default: 0.0.0.0 or input if clustered). --http-host= Embedded web server's host name. Default: localhost. --http-port= Embedded web server's port. Default: 8161. --java-memory= Define the -Xmx memory parameter for the broker. Default: 2G. --java-options= Extra Java options to be passed to the profile. --jdbc Store message data in JDBC instead of local files. --jdbc-bindings-table-name= Name of the jdbc bindings table. --jdbc-connection-url= The URL used for the database connection. --jdbc-driver-class-name= JDBC driver classname. --jdbc-large-message-table-name= Name of the large messages table. --jdbc-lock-expiration= Lock expiration (in milliseconds). --jdbc-lock-renew-period= Lock Renew Period (in milliseconds). --jdbc-message-table-name= Name of the jdbc messages table. --jdbc-network-timeout= Network timeout (in milliseconds). --jdbc-node-manager-table-name= Name of the jdbc node manager table. --jdbc-page-store-table-name= Name of the page store messages table. --journal-device-block-size= The block size of the journal's storage device. Default: 4096. --journal-retention= Configure journal retention in days. If > 0 then enable journal-retention-directory from broker. xml allowing replay options. --journal-retention-max-bytes= Maximum number of bytes to keep in the retention directory. --mapped Set the journal as mapped. --max-hops= Number of hops on the cluster configuration. --message-load-balancing= Message load balancing policy for cluster. Default: ON_DEMAND. Valid values: ON_DEMAND, STRICT, OFF, OFF_WITH_REDISTRIBUTION. --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= The user's password. Default: input. --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= How much to off-set the ports of every acceptor. --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= The name for the role created. Default: amq. --security-manager= 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= Embedded web server's key store path. --ssl-key-password= The key store's password. --ssl-trust= The trust store path in case of client authentication. --ssl-trust-password= The trust store's password. --static-cluster= 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= 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 : Type exit or press 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 --password --url ---- 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 | ----