The Command Line Interface (CLI) is a management tool for a managed domain or standalone server. It allows a user to connect to the domain controller or a standalone server and execute management operations available through the de-typed management model.
Depending on the operating system, the CLI is launched using jboss-cli.sh or jboss-cli.bat located in the WildFly bin directory. For further information on the default directory structure, please consult the "Getting Started Guide".
The first thing to do after the CLI has started is to connect to a managed WildFly instance. This is done using the command connect, e.g.
./bin/jboss-cli.sh You are disconnected at the moment. Type 'connect' to connect to the server or 'help' for the list of supported commands. [disconnected /] [disconnected /] connect [domain@localhost:9990 /] [domain@localhost:9990 /] quit Closed connection to localhost:9990
localhost:9990 is the default host and port combination for the WildFly CLI client.
The host and the port of the server can be provided as an optional parameter, if the server is not listening on localhost:9990.
./bin/jboss-cli.sh You are disconnected at the moment. Type 'connect' to connect to the server [disconnected /] connect 192.168.0.10:9990 Connected to standalone controller at 192.168.0.1:9990
The :9990 is not required as the CLI will use port 9990 by default. The port needs to be provided if the server is listening on some other port.
To terminate the session type quit.
The jboss-cli script accepts a --connect parameter: ./jboss-cli.sh --connect
The --controller parameter can be used to specify the host and port of the server: ./jboss-cli.sh --connect --controller=192.168.0.1:9990
Help is also available:
[domain@localhost:9990 /] help --commands Commands available in the current context: batch connection-factory deployment-overlay if patch reload try cd connection-info echo jdbc-driver-info pwd rollout-plan undeploy clear data-source echo-dmr jms-queue quit run-batch unset command deploy help jms-topic read-attribute set version connect deployment-info history ls read-operation shutdown xa-data-source To read a description of a specific command execute 'command_name --help'.
The CLI can also be run in non-interactive mode to support scripts and other types of command line or batch processing. The --command and --commands arguments can be used to pass a command or a list of commands to execute. Additionally a --file argument is supported which enables CLI commands to be provided from a text file.
For example the following command can be used to list all the current deployments
$ ./bin/jboss-cli.sh --connect --commands=ls\ deployment sample.war osgi-bundle.jar
The output can be combined with other shell commands for further processing, for example to find out what .war files are deployed:
$ ./bin/jboss-cli.sh --connect --commands=ls\ deployment | grep war sample.war
In order to match a command with its output, you can provide the option --echo-command (or add the XML element <echo-command> to the CLI configuration file) in order to make the CLI to include the prompt + command + options in the output. With this option enabled, any executed command will be added to the output.
By default CLI command and operation executions are not timely bounded. It means that a command never ending its execution will make the CLI process to be stuck and unresponsive. To protect the CLI from this behavior, one can set a command execution timeout.
In interactive mode, when a timeout occurs, an error message is displayed then the console prompt is made available to type new commands. In non interactive mode (executing a script or a list of commands), when a timeout occurs, an exception is thrown and the CLI execution is stopped. In both modes (interactive and non interactive), when a timeout occurs, the CLI will make a best effort to cancel the associated server side activities.
Add the XML element <command-timeout>{num seconds}</command-timeout> to the CLI XML configuration file.
Add the option --command-timeout={num seconds} to the CLI command line. This will override any value set in the XML configuration file.
Once the CLI is running, the timeout can be adjusted to cope with the commands to execute. For example a batch command will need a longer timeout than a non batch one. The command command-timeout allows to get, set and reset the command timeout.
The command command-timeout get displays the current timeout in seconds. A timeout of 0 means no timeout.
[standalone@localhost:9990 /] command-timeout get 0
The command command-timeout set update the timeout value to a number of seconds. If a timeout has been set via configuration (XML file or option), it is overridden by the set action.
[standalone@localhost:9990 /] command-timeout set 10
The command command-timeout reset {config|default} allows to set the timeout to its configuration value (XML file or option) or default value (0 second). If no configuration value is set, resetting to the configuration value sets the timeout to its default value (0 seconds).
[standalone@localhost:9990 /] command-timeout reset config [standalone@localhost:9990 /] command-timeout reset default
The native interface shares the same security configuration as the http interface, however we also support a local authentication mechanism which means that the CLI can authenticate against the local WildFly instance without prompting the user for a username and password. This mechanism only works if the user running the CLI has read access to the standalone/tmp/auth folder or domain/tmp/auth folder under the respective WildFly installation - if the local mechanism fails then the CLI will fallback to prompting for a username and password for a user configured as in Default HTTP Interface Security.
Establishing a CLI connection to a remote server will require a username and password by default.
Operation requests allow for low level interaction with the management model. They are different from the high level commands (i.e. create-jms-queue) in that they allow you to read and modify the server configuration as if you were editing the XML configuration files directly. The configuration is represented as a tree of addressable resources, where each node in the tree (aka resource) offers a set of operations to execute.
An operation request basically consists of three parts: The address, an operation name and an optional set of parameters.
The formal specification for an operation request is:
[/node-type=node-name (/node-type=node-name)*] : operation-name [( [parameter-name=parameter-value (,parameter-name=parameter-value)*] )]
For example:
/subsystem=logging/root-logger=ROOT:change-root-log-level(level=WARN)
Tab-completion is supported for all commands and options, i.e. node-types and node-names, operation names and parameter names. We are also considering adding aliases that are less verbose for the user, and will translate into the corresponding operation requests in the background.
Whitespaces between the separators in the operation request strings are not significant.
Operation requests might not always have the address part or the parameters. E.g.
:read-resource
which will list all the node types for the current node.
To syntactically disambiguate between the commands and operations, operations require one of the following prefixes:
To execute an operation against the current node, e.g.
cd subsystem=logging :read-resource(recursive="true")
To execute an operation against a child node of the current node, e.g.
cd subsystem=logging ./root-logger=ROOT:change-root-log-level(level=WARN)
To execute an operation against the root node, e.g.
/:read-resource
The operation types can be distinguished between common operations that exist on any node and specific operations that belong to a particular configuration resource (i.e. subsystem). The common operations are:
add
read-attribute
read-children-names
read-children-resources
read-children-types
read-operation-description
read-operation-names
read-resource
read-resource-description
remove
validate-address
write-attribute
For a list of specific operations (e.g. operations that relate to the logging subsystem) you can always query the model itself. For example, to read the operations supported by the logging subsystem resource on a standalone server:
[[standalone@localhost:9990 /] /subsystem=logging:read-operation-names
{
"outcome" => "success",
"result" => [
"add",
"change-root-log-level",
"read-attribute",
"read-children-names",
"read-children-resources",
"read-children-types",
"read-operation-description",
"read-operation-names",
"read-resource",
"read-resource-description",
"remove-root-logger",
"root-logger-assign-handler",
"root-logger-unassign-handler",
"set-root-logger",
"validate-address",
"write-attribute"
]
}
As you can see, the logging resource offers four additional operations, namely root-logger-assign-handler, root-logger-unassign-handler, set-root-logger and remove-root-logger.
Further documentation about a resource or operation can be retrieved through the description:
[standalone@localhost:9990 /] /subsystem=logging:read-operation-description(name=change-root-log-level)
{
"outcome" => "success",
"result" => {
"operation-name" => "change-root-log-level",
"description" => "Change the root logger level.",
"request-properties" => {"level" => {
"type" => STRING,
"description" => "The log level specifying which message levels will be logged by this logger.
Message levels lower than this value will be discarded.",
"required" => true
}}
}
}
To see the full model enter :read-resource(recursive=true).
Command (and operation request) history is enabled by default. The history is kept both in-memory and in a file on the disk, i.e. it is preserved between command line sessions. The history file name is .jboss-cli-history and is automatically created in the user's home directory. When the command line interface is launched this file is read and the in-memory history is initialized with its content.
While in the command line session, you can use the arrow keys to go back and forth in the history of commands and operations.
To manipulate the history you can use the history command. If executed without any arguments, it will print all the recorded commands and operations (up to the configured maximum, which defaults to 500) from the in-memory history.
history supports three optional arguments:
disable - will disable history expansion (but will not clear the previously recorded history);
enabled - will re-enable history expansion (starting from the last recorded command before the history expansion was disabled);
clear - will clear the in-memory history (but not the file one).
The batch mode allows one to group commands and operations and execute them together as an atomic unit. If at least one of the commands or operations fails, all the other successfully executed commands and operations in the batch are rolled back.
Not all of the commands are allowed in the batch. For example, commands like cd, ls, help, etc. are not allowed in the batch since they don't translate into operation requests. Only the commands that translate into operation requests are allowed in the batch. The batch, actually, is executed as a composite operation request.
The batch mode is entered by executing command batch.
[standalone@localhost:9990 /] batch [standalone@localhost:9990 / #] /subsystem=datasources/data-source="java\:\/H2DS":enable [standalone@localhost:9990 / #] /subsystem=messaging-activemq/server=default/jms-queue=newQueue:add
You can execute a batch using the run-batch command:
[standalone@localhost:9990 / #] run-batch The batch executed successfully.
Exit the batch edit mode without losing your changes:
[standalone@localhost:9990 / #] holdback-batch [standalone@localhost:9990 /]
Then activate it later on again:
[standalone@localhost:9990 /] batch Re-activated batch #1 /subsystem=datasources/data-source=java:/H2DS:\/H2DS:enable
There are several other notable batch commands available as well (tab complete to see the list):
clear-batch
edit-batch-line (e.g. edit-batch line 3 create-jms-topic name=mytopic)
remove-batch-line (e.g. remove-batch-line 3)
move-batch-line (e.g. move-batch-line 3 1)
discard-batch