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

A quick summary of the various commands is depicted below. Each command has a specific format to it and access control can also be enabled on it for security purposes.

Area (Server Edition)	Command name	Description
Users (Standard/Enterprise)
	users	Lists all users
	register-user	Registers a user within an Axon Server
	delete-user	Deletes a user within Axon Server
Metrics (Standard/Enterprise)
	metrics	Lists all metrics for an Axon Server
Applications (Enterprise Only)
	applications	Lists all applications within an Axon Server
	register-application	Registers an application with Axon Server
	delete-application	Deletes a registered application
Cluster (Enterprise Only)
	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. This command should be used only 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 Group (Enterprise Only)
	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
Context (Enterprise Only)
	contexts	Lists all details of registered contexts within an Axon Server EE deployment
	register-context	Creates a new context
	delete-context	Deletes a context
Plugins (Enterprise Only)
	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
Other (Standard Only)
	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, if it is omitted it defaults to http://localhost:8024.‌ While for Axon Server SE, the URL for the Axon Server SE will be the single running node, for Axon Server EE, the URL should be pointing to any node serving the _admin context within an Axon Server EE 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`	Do not 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. This needs to be provided with the -t option. When you run a command on the Axon Server node itself from the directory where Axon Server was started, you don't have to provide a token.‌

For Axon Server Standard Edition the token is specified in the axonserver.properties file (property name = axoniq.axonserver.token). In Enterprise Edition you need to register an application with ADMIN role, and you can use that application's token to perform command line commands remotely.‌ The token needs to be supplied 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. For Axon Server SE, the URL for the Axon Server SE will be the single running node, while for Axon Server EE the URL should be pointing to any node serving the _admin context within an Axon Server EE cluster.

• -t refers to the access token to authenticate at the server to which the command is sent to.

Users

When using Axon Server with access control enabled, users need to be defined 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

• -S refers to the server to send the command to and if not supplied connects by default to http://localhost:8024. For Axon Server SE, the URL for the Axon Server SE will be the single running node, while for Axon Server EE the URL should be pointing to any node serving the _admin context within an Axon Server EE cluster.

• -t refers to the access token to authenticate at the server to which the command is sent to.

register-user‌

Registers a user with specified roles. For Axon Server SE, the only two roles possible are READ/ADMIN while for Axon Server EE, 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}. For Axon Server SE, the only context available is the default context so the role will only apply to that context (hence not necessary to supply the context name). For Axon Server EE, the specific context can be included as required. Also if no context is mentioned in Axon Server EE, 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), e.g. 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

• -S refers to the server to send the command to and if not supplied connects by default to http://localhost:8024. For Axon Server SE, the URL for the Axon Server SE will be the single running node, while for Axon Server EE the URL should be pointing to any node serving the _admin context within an Axon Server EE cluster.

• -t refers to the access token to authenticate at the server to which the command is sent to.

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

• -S refers to the server to send the command to and if not supplied connects by default to http://localhost:8024. For Axon Server SE, the URL for the Axon Server SE will be the single running node, while for Axon Server EE the URL should be pointing to any node serving the _admin context within an Axon Server EE cluster.

• -t refers to the access token to authenticate at the server to which the command is sent to.

Metrics

Overview of all Axon specific metrics.‌

$ java -jar axonserver-cli.jar metrics 

Optional parameters

• -S refers to the server to send the command to and if not supplied connects by default to http://localhost:8024. For Axon Server SE, the URL for the Axon Server SE will be the single running node, while for Axon Server EE the URL should be pointing to any node serving the _admin context within an Axon Server EE cluster.

• -t refers to the access token to authenticate at the server to which the command is sent to.

Applications (Enterprise Edition only)

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

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

• -t refers to the access token to authenticate at the server to which the command is sent to.

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, e.g.:

$ 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), e.g. 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.

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

• -t refers to the access token to authenticate at the server to which the command is sent to.

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

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

• -t refers to the access token to authenticate at the server to which the command is sent to.

Cluster (Enterprise Edition only)‌

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

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

• -t refers to the access token to authenticate at the server to which the command is sent to.

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 no context is specified the default context is created

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

• -t refers to the access token to authenticate at the server to which the command is sent to.

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 the node that needs to be added to 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 is 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.

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

• -t refers to the access token to authenticate at the server to which the command is sent to.

unregister-node‌

Removes the node with specified name from the cluster. After this, the node that is deleted will still be running 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

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

• -t refers to the access token to authenticate at the server to which the command is sent to.

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

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

• -t refers to the access token to authenticate at the server to which the command is sent to.

Replication Groups (Enterprise Edition only)

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

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

• -t refers to the access token to authenticate at the server to which the command is sent to.

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

• -S if not supplied connects by default to http://localhost:8024. If supplied, it should be any node serving the _admin context.

• -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.

• -t refers to the access token to authenticate at the server to which the command is sent to.

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

• -S if not supplied connects by default to http://localhost:8024. If supplied, it should be any node serving the _admin context.

• -t refers to the access token to authenticate at the server to which the command is sent to.

• ** --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

• -S if not supplied connects by default to http://localhost:8024. If supplied, it should be any node serving the _admin context.

• -t refers to the access token to authenticate at the server to which the command is sent to.

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

• -S if not supplied connects by default to http://localhost:8024. If supplied, it should be any node serving the _admin context.

• -t refers to the access token to authenticate at the server to which the command is sent to.

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

Contexts (Enterprise Edition only)

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

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

• -t refers to the access token to authenticate at the server to which the command is sent to.

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

• -S if not supplied connects by default to http://localhost:8024. If supplied, it should be any node serving the _admin context.

• -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.

• -t refers to the access token to authenticate at the server to which the command is sent to.

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

• -S if not supplied connects by default to http://localhost:8024. If supplied, it should be any node serving the _admin context.

• -t refers to the access token to authenticate at the server to which the command is sent to.

• ** --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

• -S if not supplied connects by default to http://localhost:8024. If supplied, it should be any node serving the _admin context.

• -t refers to the access token to authenticate at the server to which the command is sent to.

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

• -S if not supplied connects by default to http://localhost:8024. If supplied, it should be any node serving the _admin context.

• -t refers to the access token to authenticate at the server to which the command is sent to.

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, may be provided multiple times

• -S if not supplied connects by default to http://localhost:8024. If supplied, it should be any node serving the _admin context.

• -t refers to the access token to authenticate at the server to which the command is sent to.

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

• -S if not supplied connects by default to http://localhost:8024. If supplied, it should be any node serving the _admin context.

• -t refers to the access token to authenticate at the server to which the command is sent to.

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

• -S if not supplied connects by default to http://localhost:8024. If supplied, it should be any node serving the _admin context.

• -t refers to the access token to authenticate at the server to which the command is sent to.

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

• -S if not supplied connects by default to http://localhost:8024. If supplied, it should be any node serving the _admin context.

• -t refers to the access token to authenticate at the server to which the command is sent to.

delete-v

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

$ java -jar ./axonserver-cli.jar unregister-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

• -S if not supplied connects by default to http://localhost:8024. If supplied, it should be any node serving the _admin context.

• -t refers to the access token to authenticate at the server to which the command is sent to.