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-Line Options
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
(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
update-license
Uploads a new license file to the cluster
(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:
1
java -jar axonserver-cli.jar <Command> <command options> -S <server-to-send-command-to> -t <auth_token>
Copied!
Or when running from a bash-like shell:
1
axonserver-cli.jar <Command> <command options> -S <server-to-send-command-to> -t <auth_token>
Copied!
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.

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.‌
1
$ java -jar axonserver-cli.jar users [-o json]
Copied!
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.
1
$ java -jar axonserver-cli.jar register-user -u <username> -r <roles> [-p <password>]
Copied!
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.
1
$ java -jar axonserver-cli.jar delete-user -u <username>
Copied!
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.‌
1
$ java -jar axonserver-cli.jar metrics
Copied!
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.‌
1
$ java -jar axonserver-cli.jar applications [-o json]
Copied!
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.:
1
$ java -jar axonserver-cli.jar register-application -a <name> -r <roles> [-d <description>] [-T <apptoken>]
Copied!
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
1
$ java -jar axonserver-cli.jar delete-application -a <name>
Copied!
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.‌
1
$ java -jar axonserver-cli.jar cluster [-o json]
Copied!
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.
1
$ java -jar axonserver-cli.jar init-cluster [-c <context>]
Copied!
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.
1
$ java -jar axonserver-cli.jar register-node -h <node-internal-host-name> [-p <internal-grpc-port>] [-c <context>] [--no-contexts]
Copied!
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.‌
1
$ java -jar axonserver-cli.jar unregister-node -n <nodename>
Copied!
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.
1
$ java -jar axonserver-cli.jar update-license -f <license-file>
Copied!
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.‌
1
$ java -jar axonserver-cli.jar replication-groups [-o json]
Copied!
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:
1
$ java -jar ./axonserver-cli.jar register-replication-group -g <name> -n <members> [-a <members>] [-m <members>] [-p <members>] [-s <members>]
Copied!
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:
1
$ java -jar ./axonserver-cli.jar delete-replication-group -g [replication-group-name] [--preserve-event-store]
Copied!
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.
1
$ java -jar ./axonserver-cli.jar add-node-to-replication-group -g <replication-group-name> -n <node> -r <role>
Copied!
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:
1
$ java -jar ./axonserver-cli.jar delete-node-from-replication-group -g <replication-group-name> -n <node name> [--preserve-event-store]
Copied!
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.‌
1
$ java -jar axonserver-cli.jar contexts [-o json]
Copied!
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:
1
$ java -jar ./axonserver-cli.jar register-context -c <context-name> -g <replication-group-name> [-n <members>]‌ [-a <members>] [-m <members>] [-p <members>]
Copied!
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:
1
$ java -jar ./axonserver-cli.jar delete-context -c <context-name> -S http://<node>:<port>
Copied!
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.
1
$ java -jar ./axonserver-cli.jar plugins [-o json]
Copied!
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.
1
$ java -jar ./axonserver-cli.jar upload-plugin -f <file>
Copied!
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.
1
$ java -jar ./axonserver-cli.jar configure-plugin -p <plugin> -v <version> -c <context> [ --prop <property> | -f <file]
Copied!
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.
1
$ java -jar ./axonserver-cli.jar activate-plugin -p <plugin> -v <version> -c <context>
Copied!
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.
1
$ java -jar ./axonserver-cli.jar pause-plugin -p <plugin> -v <version> -c <context>
Copied!
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.
1
$ java -jar ./axonserver-cli.jar unregister-plugin -p <plugin> -v <version> -c <context>
Copied!
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.
1
$ java -jar ./axonserver-cli.jar unregister-plugin -p <plugin> -v <version>
Copied!
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.
Last modified 6mo ago