keycloak-scim/server_installation/topics/config-subsystem/start-cli.adoc

[[_start_cli]]

=== Starting the {appserver_name} CLI
Besides editing the configuration by hand, you also have the option of changing
the configuration by issuing commands via the _jboss-cli_ tool.  CLI allows
you to configure servers locally or remotely.  And it is especially useful when
combined with scripting.

To start the {appserver_name} CLI, you need to run `jboss-cli`.

.Linux/Unix
[source]
----
$ .../bin/jboss-cli.sh
----

.Windows
[source]
----
> ...\bin\jboss-cli.bat
----

This will bring you to a prompt like this:

.Prompt
[source]
----
[disconnected /]
----

If you wish to execute commands on a running server, you will first
execute the `connect` command.

.connect
[source]
----
[disconnected /] connect
connect
[standalone@localhost:9990 /]
----

You may be thinking to yourself, "I didn't enter in any username or password!".  If you run `jboss-cli` on the same machine
as your running standalone server or domain controller and your account has appropriate file permissions, you do not have
to setup or enter in an admin username and password.  See the link:{appserver_admindoc_link}[_{appserver_admindoc_name}_]
for more details on how to make things more secure if you are uncomfortable with that setup.

=== CLI embedded mode

If you do happen to be on the same machine as your standalone server and you want to
issue commands while the server is not active, you can embed the server into CLI and make
changes in a special mode that disallows incoming requests.  To do this, first
execute the `embed-server` command with the config file you wish to change.

.embed-server
[source]
----
[disconnected /] embed-server --server-config=standalone.xml
[standalone@embedded /]
----

=== Using CLI GUI mode

The CLI can also run in GUI mode.  GUI mode launches a Swing application that
allows you to graphically view and edit the entire management model of a _running_ server.
GUI mode is especially useful when you need help formatting your CLI commands and learning
about the options available.  The GUI can also retrieve server logs from a local or
remote server.

.Procedure

. Start the CLI in GUI mode
+
[source]
----
$ .../bin/jboss-cli.sh --gui
----
+
Note: to connect to a remote server, you pass the `--connect` option as well.
Use the --help option for more details.

. Scroll down to find the node `subsystem=keycloak-server`.

. Right-click the node and select `Explore subsystem=keycloak-server`.
+
A new tab displays only the keycloak-server subsystem.
+
.keycloak-server subsystem
image:images/cli-gui.png[keycloak-server subsystem]

=== CLI scripting

The CLI has extensive scripting capabilities.  A script is just a text
file with CLI commands in it.  Consider a simple script that turns off theme
and template caching.

.turn-off-caching.cli
[source]
----
/subsystem=keycloak-server/theme=defaults/:write-attribute(name=cacheThemes,value=false)
/subsystem=keycloak-server/theme=defaults/:write-attribute(name=cacheTemplates,value=false)
----
To execute the script, you can follow the `Scripts` menu in CLI GUI, or execute the
script from the command line as follows:
[source]
----
$ .../bin/jboss-cli.sh --file=turn-off-caching.cli
----