Command Line Interface

The Axon Server provides a command line utility which allows for updating the Axon Server configuration through scripts or from the command line interface. The utility is available as a jar file (axonserver-cli.jar) which is available as part of the Axon Server distributable (SE/EE).

Quick summary

The following table shows a quick summary of the various commands. Each command has a specific Format to it and may require access control on it for security purposes.

Command name

Description

users

Lists all users

register-user

Registers a user within an Axon Server

delete-user

Deletes a user within Axon Server

metrics

Lists all metrics for an Axon Server

applications

Lists all applications within an Axon Server

register-application

Registers an application with Axon Server

delete-application

Deletes a registered application

cluster

Lists all the details of a cluster within an Axon Server EE deployment

init-cluster

Initiates a cluster within an Axon Server EE deployment

register-node

Registers a node as a member within a cluster

unregister-node

Unregisters a member node within a cluster. You should only use this command if you want to permanently remove the node from the cluster. Use with caution.

update-license

Uploads a new license file to the cluster

replication-groups

Lists all details of registered replication groups within an Axon Server EE deployment

add-node-to-replication-group

Adds a node as a member of a replication group

register-replication-group

Creates a new replication group

delete-node-from-replication-group

Unregisters a member node of a replication group

delete-replication-group

Deletes a replication group

contexts

Lists all details of registered contexts within an Axon Server EE deployment

register-context

Creates a new context

update-context

Updates one or multiple properties in an existing context

delete-context

Deletes a context

plugins

Lists all details of installed plugins

upload-plugin

Upload a plugin package

configure-plugin

Configures a plugin for a context

active-plugin

Activates a plugin for a context

pause-plugin

Temporarily stops a plugin for a context

unregister-plugin

Unregisters a plugin for a context

delete-plugin

Deletes a plugin package

purge-events

Purges events from an Event Store

Format

The general format of any command line command is:

java -jar axonserver-cli.jar <Command> <command options> -S <server-to-send-command-to> -t <auth_token>

Or when running from a bash-like shell:

axonserver-cli.jar <Command>  <command options> -S <server-to-send-command-to> -t <auth_token>

The option -S with the URL to the Axon Server is optional, it defaults to http://localhost:8024.The URL must point to any node serving the _admin context within an Axon Server cluster.

The <command options> valid for all commands, are: -S, -s, -i, -o. Their effect is described in the table below.

Option - Short Option - Long Description

-S

server

Server to send command to (default http://localhost:8024)

-s

https

Use HTTPS (SSL,TLS) to connect to the server, rather than HTTP.

-i

insecure-ssl

Don’t check the certificate when connecting using HTTPS.

-o

output

Output format (txt,json)

For options specific to individual commands, see the descriptions of the commands below.

Access control

When running Axon Server with access control enabled, executing commands remotely requires an access token. You need to provide this token with the -t option. When you run a command on the Axon Server node itself from the directory where you started Axon Server, you don’t have to provide a token.

To send command line requests from another node or from another directory, you need to register an application with ADMIN role. When you register an application, Axon Server generates a token, if you did not specify one. You need to supply this token using the -t option in any of the commands.

Commands

This section describes all commands supported by the command line interface, grouped by the specific area. For all command line commands there are 2 common (optional) parameters:

  • -S refers to the server to send the command to and if not supplied connects by default to http://localhost:8024. The URL must point to any node serving the _admin context within an Axon Server cluster.

  • -t refers to the access token to authenticate at the server.

Users

When using Axon Server with access control enabled, you need to define user to access the Axon Server Console’s Dashboard. Users with only READ role can view the information in the console dashboard but not make any changes, users with ADMIN role can make changes.

users

Returns a list of all registered users and their roles.

$ java -jar axonserver-cli.jar users [-o json]

Optional parameters

  • -o produces output in JSON format instead of formatted text

register-user

Registers a user with specified roles. The following roles can be granted

  • ADMIN

  • CONTEXT_ADMIN

  • DISPATCH_COMMANDS

  • DISPATCH_QUERY

  • MONITOR

  • PUBLISH_EVENTS

  • READ_EVENTS

  • SUBSCRIBE_COMMAND_HANDLER

  • SUBSCRIBE_QUERY_HANDLER

  • USE_CONTEXT

  • VIEW_CONFIGURATION

In addition to the role name you can also supply the context to which this role applies like {role_name}@{context_name}. If no context is mentioned in the request, the role is granted to the user for all registered contexts.

$ java -jar axonserver-cli.jar register-user -u <username> -r <roles> [-p <password>]

Mandatory parameters

  • -u refers to the username.

  • -r refers to the role of the user. Specify multiple roles by giving a comma separated list (without spaces), for example READ,ADMIN.

  • -p refers to the password of the user. If you do not specify a password with the -p option, the command line interface will prompt you for one.

Optional parameters

delete-user

Deletes the specified user.

$ java -jar axonserver-cli.jar delete-user -u <username>

Mandatory parameters

  • -u refers to the username of the user that needs to be deleted.

Optional parameters

Metrics

Overview of all Axon specific metrics.

$ java -jar axonserver-cli.jar metrics

Optional parameters

Applications

applications

Lists all applications and the roles per application per context.

$ java -jar axonserver-cli.jar applications [-o json]

Optional parameters

  • -o produces output in JSON format instead of formatted text

register-application

Registers an application with specified name and role. The following roles can be granted:

  • ADMIN

  • CONTEXT_ADMIN

  • DISPATCH_COMMANDS

  • DISPATCH_QUERY

  • MONITOR

  • PUBLISH_EVENTS

  • READ_EVENTS

  • SUBSCRIBE_COMMAND_HANDLER

  • SUBSCRIBE_QUERY_HANDLER

  • USE_CONTEXT

  • VIEW_CONFIGURATION

In addition to the role name you can also supply the context to which this role applies like {role_name}@{context_name}. Also if no context is mentioned in Axon Server EE, the role is granted to the application for all registered contexts.

This command returns the generated token to use. Note that this token is only generated once, if you lose it you must delete the application and register it again to get a new token. If you want to define the token yourself, you can provide one in the command line command using the -T flag, for example:

$ java -jar axonserver-cli.jar register-application -a <name> -r <roles>  [-d <description>] [-T <apptoken>]

Mandatory parameters

  • -a refers to the name of the application

  • -r refers to the role of the application. Specify multiple roles by giving a comma separated list (without spaces), for example READ,ADMIN.

Optional parameters

  • -d refers to the description of the application.

  • -T in case you want to define the token yourself for newly registered application.

delete-application

Deletes the application from Axon Server EE

$ java -jar axonserver-cli.jar delete-application -a <name>

Mandatory parameters

  • -a refers to the name of the application

Optional parameters

Cluster

cluster

Shows all the nodes in the cluster, including their hostnames, HTTP ports and gRPC ports.

$ java -jar axonserver-cli.jar cluster [-o json]

Optional parameters

  • -o produces output in JSON format instead of formatted text

init-cluster

Initializes the cluster, creates the _admin context and the specified context.

$ java -jar axonserver-cli.jar init-cluster [-c <context>]

Optional parameters

  • -c refers to the context that needs to be created along with the _admin context. If the caller does not specify a context Axon Server creates a context called default.

register-node

Registers an Axon Server node with a cluster.

$ java -jar axonserver-cli.jar register-node -h <node-internal-host-name> [-p <internal-grpc-port>] [-c <context>] [--no-contexts]

If you specify a context, the new node will be a member of the specified context. If you haven’t specified a context, the new node will become a member of all defined contexts.

Mandatory parameters

  • -h refers to the internal host name of a node that is already an _admin node for the cluster.

Optional parameters

  • -p refers to the internal gRPC port of the node that needs to be added to the cluster. By default, it’s 8224.

  • -c refers to the context which this axon server node will be a member of. If no context is specified, the new node will become a member of all defined contexts.

  • –no-contexts will add the node to the cluster but will not register it to any of the defined contexts.

unregister-node

Removes the node with specified name from the cluster. After this, the deleted node still runs in standalone mode.

$ java -jar axonserver-cli.jar unregister-node -n <nodename>

Mandatory parameters

  • -n refers to the name of the node that needs to be removed from the cluster.

Optional parameters

update-license

Uploads a new license file to the cluster. Axon Server distributes the new license file to all nodes in the cluster.

$ java -jar axonserver-cli.jar update-license -f <license-file>

Mandatory parameters

  • -f refers to the file containing the license to update.

Optional parameters

Replication groups

replication-groups

Lists all replication groups and the nodes assigned to the replication groups. For each replication groups it shows the name of the replication group, the master node for the replication group and the member nodes of the replication group.

$ java -jar axonserver-cli.jar replication-groups [-o json]

Optional parameters

  • -o produces output in JSON format instead of formatted text

register-replication-group

The register-replication-group command helps in the registration and creation of a new replication group. A sample of the command with the mandatory parameters is depicted below:

$ java -jar ./axonserver-cli.jar register-replication-group  -g <name> -n <members> [-a <members>] [-m <members>] [-p <members>] [-s <members>]

Mandatory parameters

  • -g refers to the replication group name. The replication group name must match the following regular expression "[a-zA-Z][a-zA-Z_-0-9]*", so it should start with a letter (uppercase or lowercase), followed by a combination of letters, digits, hyphens and underscores.

  • -n refers to the comma separated list of node names that should be members of the new replication group. This parameter registers them as "PRIMARY" member nodes of that context.

Optional parameters

  • -a refers to the comma separated list of node names that should be "ACTIVE_BACKUP" member nodes of that replication group.

  • -m refers to the comma separated list of node names that should be "MESSAGING_ONLY" member nodes of that replication group.

  • -p refers to the comma separated list of node names that should be "PASSIVE_BACKUP" member nodes of that replication group.

  • -p refers to the comma separated list of node names that should be "SECONDARY" member nodes of that replication group.

delete-replication-group

The delete-replication-group command helps in the deletion of a replication group and its associated data from all member nodes of that replication group. A sample of the command with the mandatory parameters is depicted below:

$ java -jar ./axonserver-cli.jar delete-replication-group  -g [replication-group-name] [--preserve-event-store]

Mandatory parameters

  • -g refers to the replication group that needs to be deleted.

Optional parameters

  • * –preserve-event-store* option to keep all the event store data for all the nodes in the replication group (false by default)

add-node-to-replication-group

The add-node-to-replication-group command helps in the registration of a new member node creation of an existing replication group.

$ java -jar ./axonserver-cli.jar add-node-to-replication-group -g <replication-group-name> -n <node> -r <role>

Mandatory parameters

  • -g refers to an existing replication group.

  • -n refers to the node name that should be a member of this replication group.

  • -r refers to the role of this node within the replication group (PRIMARY/MESSAGING_ONLY/ACTIVE_BACKUP/PASSIVE_BACKUP/SECONDARY).

Optional parameters

delete-node-from-replication-group

The delete-node-from-replication-group command helps in the deletion member node from an existing replication group. A sample of the command with the mandatory parameters is depicted below:

$ java -jar ./axonserver-cli.jar delete-node-from-replication-group  -g <replication-group-name> -n <node name> [--preserve-event-store]

Mandatory parameters

  • -g refers to an existing replication group.

  • -n refers to the node name that should no longer be a member of this context.

Optional parameters

  • –preserve-event-store removes the node from the replication group but leaves the event store files on that node.

Contexts

contexts

Lists all contexts and the nodes assigned to the contexts. For each context it shows the name of the context, the master node for the context and the member nodes of the context.

$ java -jar axonserver-cli.jar contexts [-o json]

Optional parameters

  • -o produces output in JSON format instead of formatted text

register-context

The register-context command helps in the registration and creation of a new context. A sample of the command with the mandatory parameters is depicted below:

$ java -jar ./axonserver-cli.jar register-context  -c <context-name> -g <replication-group-name> [-n <members>] [-a <members>] [-m <members>] [-p <members>]

If you don’t provide an existing replication group name, you need to provide the names and roles of the nodes to include in the replication group to create. If you don’t provide a replication group name, but do provide nodes, it will create a replication group with the same name as the context.

Mandatory parameters

  • -c refers to the context name. The context name must match the following regular expression "[a-zA-Z][a-zA-Z_-0-9]*", so it should start with a letter (uppercase or lowercase), followed by a combination of letters, digits, hyphens and underscores.

Optional parameters

  • -g refers to the name of the replication group

  • -n refers to the comma separated list of node names that should be members of the new context. This parameter registers them as "PRIMARY" member nodes of that context.

  • -a refers to the comma separated list of node names that should be "ACTIVE_BACKUP" member nodes of that context.

  • -m refers to the comma separated list of node names that should be "MESSAGING_ONLY" member nodes of that context.

  • -p refers to the comma separated list of node names that should be "PASSIVE_BACKUP" member nodes of that context.

  • -s refers to the comma separated list of node names that should be "SECONDARY" member nodes of that context.

delete-context

The delete-context command helps in the deletion of a context and its associated data from all member nodes of that context. A sample of the command with the mandatory parameters is depicted below:

$ java -jar ./axonserver-cli.jar delete-context  -c <context-name> -S http://<node>:<port>

Mandatory parameters

  • -c refers to the context that needs to be deleted.

Optional parameters

  • * –preserve-event-store* option to keep the event store data (false by default).

Plugins

plugins

Lists all the installed plugins and their status per context.

$ java -jar ./axonserver-cli.jar plugins [-o json]

Optional parameters

  • -o produces output in JSON format instead of formatted text

upload-plugin

Uploads a new plugin package to Axon Server. In Enterprise Edition this command needs to be targetted to an _admin node.

$ java -jar ./axonserver-cli.jar upload-plugin -f <file>

Mandatory parameters

  • -f refers to the jar file containing the OSGi bundle for the plugin

Optional parameters

configure-plugin

Configures a plugin for a specific context.

$ java -jar ./axonserver-cli.jar configure-plugin -p <plugin> -v <version> -c <context> [ --prop <property> | -f <file]

Mandatory parameters

  • -p refers to the name of the plugin

  • -v refers to the version of the plugin

  • -c refers to the context where the configuration of the plugin applies

Optional parameters

  • -f YAML file containing properties

  • -prop property group, name and value for a configuration property, repeat multiple times for multiple properties

activate-plugin

Activates a plugin for a specific context.

$ java -jar ./axonserver-cli.jar activate-plugin -p <plugin> -v <version> -c <context>

Mandatory parameters

  • -p refers to the name of the plugin

  • -v refers to the version of the plugin

  • -c refers to the context for which to activate the plugin

Optional parameters

pause-plugin

Pauses an plugin for a specific context.

$ java -jar ./axonserver-cli.jar pause-plugin -p <plugin> -v <version> -c <context>

Mandatory parameters

  • -p refers to the name of the plugin

  • -v refers to the version of the plugin

  • -c refers to the context for which to pause the plugin

Optional parameters

unregister-plugin

Removes a plugin for a specific context.

$ java -jar ./axonserver-cli.jar unregister-plugin -p <plugin> -v <version> -c <context>

Mandatory parameters

  • -p refers to the name of the plugin

  • -v refers to the version of the plugin

  • -c refers to the context for which to unregister the plugin

Optional parameters

delete-plugin

Removes an plugin from all Axon Server nodes and for all contexts.

$ java -jar ./axonserver-cli.jar delete-plugin -p <plugin> -v <version>

Mandatory parameters

  • -p refers to the name of the v

  • -v refers to the version of the plugin

Optional parameters