<commit_before>= Command Line Utilities
:page-shortname: command-line-utilities
:page-permalink: command-line-utilities.html

Solr's Administration page (found by default at `\http://hostname:8983/solr/`), provides a section with menu items for monitoring indexing and performance statistics.

This pag also includes information about index distribution and replication, and information on all threads running in the JVM at the time.

There is also a section where you can run queries, and an assistance area.

In addition, SolrCloud provides its own administration page (found at http://localhost:8983/solr/#/~cloud), as well as a few tools available via a ZooKeeper Command Line Utility (CLI). The CLI scripts found in `server/scripts/cloud-scripts` let you upload configuration information to ZooKeeper, in the same two ways that were shown in the examples in <<parameter-reference.adoc#parameter-reference,Parameter Reference>>. It also provides a few other commands that let you link collection sets to collections, make ZooKeeper paths or clear them, and download configurations from ZooKeeper to the local filesystem.

.Solr's zkcli.sh vs ZooKeeper's zkCli.sh vs Solr Start Script
[IMPORTANT]
====
The `zkcli.sh` provided by Solr is not the same as the https://zookeeper.apache.org/doc/trunk/zookeeperStarted.html#sc_ConnectingToZooKeeper[`zkCli.sh` included in ZooKeeper distributions].

ZooKeeper's `zkCli.sh` provides a completely general, application-agnostic shell for manipulating data in ZooKeeper. Solr's `zkcli.sh` – discussed in this section – is specific to Solr, and has command line arguments specific to dealing with Solr data in ZooKeeper.

Many of the functions provided by the zkCli.sh script are also provided by the <<solr-control-script-reference.adoc#solr-control-script-reference,Solr Control Script Reference>>, which may be more familiar as the start script ZooKeeper maintenance commands are very similar to Unix commands.
====

[[CommandLineUtilities-UsingSolr_sZooKeeperCLI]]
== Using Solr's ZooKeeper CLI

Both `zkcli.sh` (for Unix environments) and `zkcli.bat` (for Windows environments) support the following command line options:

// TODO: Change column width to %autowidth.spread when https://github.com/asciidoctor/asciidoctor-pdf/issues/599 is fixed

[cols="10,30,60",options="header"]
|===
|Short |Parameter Usage |Meaning
| |`-cmd <arg>` |CLI Command to be executed: `bootstrap`, `upconfig`, `downconfig`, `linkconfig`, `makepath`, `get`, `getfile`, `put`, `putfile`, `list`, `clear` or `clusterprop`. This parameter is **mandatory**.
|`-z` |`-zkhost <locations>` |ZooKeeper host address. This parameter is *mandatory* for all CLI commands.
|`-c` |`-collection <name>` |For `linkconfig`: name of the collection.
|`-d` |`-confdir <path>` |For `upconfig`: a directory of configuration files. For downconfig: the destination of files pulled from ZooKeeper
|`-h` |`-help` |Display help text.
|`-n` |`-confname <arg>` |For `upconfig`, `linkconfig`, `downconfig`: name of the configuration set.
|`-r` |`-runzk <port>` |Run ZooKeeper internally by passing the Solr run port; only for clusters on one machine.
|`-s` |`-solrhome <path>` |For `bootstrap` or when using `-runzk`: the *mandatory* solrhome location.
| |`-name <name>` |For `clusterprop`: the *mandatory* cluster property name.
| |`-val <value>` |For `clusterprop`: the cluster property value. If not specified, *null* will be used as value.
|===

The short form parameter options may be specified with a single dash (eg: `-c mycollection`).

The long form parameter options may be specified using either a single dash (eg: `-collection mycollection`) or a double dash (eg: `--collection mycollection`)

[[CommandLineUtilities-ZooKeeperCLIExamples]]
== ZooKeeper CLI Examples

Below are some examples of using the `zkcli.sh` CLI which assume you have already started the SolrCloud example (`bin/solr -e cloud -noprompt`)

If you are on Windows machine, simply replace `zkcli.sh` with `zkcli.bat` in these examples.

[[CommandLineUtilities-Uploadaconfigurationdirectory]]
=== Upload a configuration directory

[source,bash]
----
./server/scripts/cloud-scripts/zkcli.sh -zkhost 127.0.0.1:9983 -cmd upconfig -confname my_new_config -confdir server/solr/configsets/basic_configs/conf
----

[[CommandLineUtilities-BootstrapZooKeeperfromexistingSOLR_HOME]]
=== Bootstrap ZooKeeper from existing SOLR_HOME

[source,bash]
----
./server/scripts/cloud-scripts/zkcli.sh -zkhost 127.0.0.1:2181 -cmd bootstrap -solrhome /var/solr/data
----

.Bootstrap with chroot
[NOTE]
====
Using the boostrap command with a zookeeper chroot in the -zkhost parameter, e.g. `-zkhost 127.0.0.1:2181/solr`, will automatically create the chroot path before uploading the configs.
====

[[CommandLineUtilities-PutarbitrarydataintoanewZooKeeperfile]]
=== Put arbitrary data into a new ZooKeeper file

[source,bash]
----
./server/scripts/cloud-scripts/zkcli.sh -zkhost 127.0.0.1:9983 -cmd put /my_zk_file.txt 'some data'
----

[[CommandLineUtilities-PutalocalfileintoanewZooKeeperfile]]
=== Put a local file into a new ZooKeeper file

[source,bash]
----
./server/scripts/cloud-scripts/zkcli.sh -zkhost 127.0.0.1:9983 -cmd putfile /my_zk_file.txt /tmp/my_local_file.txt
----

[[CommandLineUtilities-Linkacollectiontoaconfigurationset]]
=== Link a collection to a configuration set

[source,bash]
----
./server/scripts/cloud-scripts/zkcli.sh -zkhost 127.0.0.1:9983 -cmd linkconfig -collection gettingstarted -confname my_new_config
----

[[CommandLineUtilities-CreateanewZooKeeperpath]]
=== Create a new ZooKeeper path

[source,bash]
----
./server/scripts/cloud-scripts/zkcli.sh -zkhost 127.0.0.1:2181 -cmd makepath /solr
----

This can be useful to create a chroot path in ZooKeeper before first cluster start.

[[CommandLineUtilities-Setaclusterproperty]]
=== Set a cluster property

This command will add or modify a single cluster property in `clusterprops.json`. Use this command instead of the usual getfile -> edit -> putfile cycle. Unlike the CLUSTERPROP REST API, this command does *not* require a running Solr cluster.

[source,bash]
----
./server/scripts/cloud-scripts/zkcli.sh -zkhost 127.0.0.1:2181 -cmd clusterprop -name urlScheme -val https
----<commit_msg>Ref Guide: Update list of available zkcli commands from SOLR-10430; rework page a bit<commit_after>= Command Line Utilities
:page-shortname: command-line-utilities
:page-permalink: command-line-utilities.html

A ZooKeeper Command Line Interface (CLI) script is available to allow you to interact directly with Solr configuration files stored in ZooKeeper.

While Solr's Administration UI includes pages dedicated to the state of your SolrCloud cluster, it does not allow you to download or modify related configuration files.

TIP: See the section <<cloud-screens.adoc#cloud-screens,Cloud Screens>> for more information about using the Admin UI screens.

The ZooKeeper CLI scripts found in `server/scripts/cloud-scripts` let you upload configuration information to ZooKeeper, in the same ways shown in the examples in <<parameter-reference.adoc#parameter-reference,Parameter Reference>>. It also provides a few other commands that let you link collection sets to collections, make ZooKeeper paths or clear them, and download configurations from ZooKeeper to the local filesystem.

Many of the functions provided by the zkCli.sh script are also provided by the <<solr-control-script-reference.adoc#solr-control-script-reference,Solr Control Script>>, which may be more familiar as the start script ZooKeeper maintenance commands are very similar to Unix commands.

.Solr's zkcli.sh vs ZooKeeper's zkCli.sh
[IMPORTANT]
====
The `zkcli.sh` provided by Solr is not the same as the https://zookeeper.apache.org/doc/trunk/zookeeperStarted.html#sc_ConnectingToZooKeeper[`zkCli.sh` included in ZooKeeper distributions].

ZooKeeper's `zkCli.sh` provides a completely general, application-agnostic shell for manipulating data in ZooKeeper. Solr's `zkcli.sh` – discussed in this section – is specific to Solr, and has command line arguments specific to dealing with Solr data in ZooKeeper.
====

[[CommandLineUtilities-UsingSolr_sZooKeeperCLI]]
== Using Solr's ZooKeeper CLI

Use the `help` option to get a list of available commands from the script itself, as in `./server/scripts/cloud-scrips/zkcli.sh help`.

Both `zkcli.sh` (for Unix environments) and `zkcli.bat` (for Windows environments) support the following command line options:

// TODO: Change column width to %autowidth.spread when https://github.com/asciidoctor/asciidoctor-pdf/issues/599 is fixed

`-cmd <arg>`::
The CLI Command to be executed. This parameter is *mandatory*. The following commands are supported:

* `bootstrap`
* `upconfig`
* `downconfig`
* `linkconfig`
* `makepath`
* `get` and `getfile`
* `put` and `putfile`
* `clear`
* `list`
* `ls`
* `clusterprop`

`-z` or `-zkhost <locations>`::
ZooKeeper host address. This parameter is *mandatory* for all CLI commands.

`-c` or `-collection <name>`::
For `linkconfig`: name of the collection.

`-d` or `-confdir <path>`::
For `upconfig`: a directory of configuration files. For downconfig: the destination of files pulled from ZooKeeper

`-h` or `-help`::
Display help text.

`-n` or `-confname <arg>`::
For `upconfig`, `linkconfig`, `downconfig`: name of the configuration set.

`-r` or `-runzk <port>`::
Run ZooKeeper internally by passing the Solr run port; only for clusters on one machine.

`-s` or `-solrhome <path>`:: For `bootstrap` or when using `-runzk`: the *mandatory* solrhome location.

`-name <name>`::
For `clusterprop`: the *mandatory* cluster property name.

`-val <value>`::
For `clusterprop`: the cluster property value. If not specified, *null* will be used as value.

[TIP]
====
The short form parameter options may be specified with a single dash (eg: `-c mycollection`).

The long form parameter options may be specified using either a single dash (eg: `-collection mycollection`) or a double dash (eg: `--collection mycollection`)
====

[[CommandLineUtilities-ZooKeeperCLIExamples]]
== ZooKeeper CLI Examples

Below are some examples of using the `zkcli.sh` CLI which assume you have already started the SolrCloud example (`bin/solr -e cloud -noprompt`)

If you are on Windows machine, simply replace `zkcli.sh` with `zkcli.bat` in these examples.

[[CommandLineUtilities-Uploadaconfigurationdirectory]]
=== Upload a configuration directory

[source,bash]
----
./server/scripts/cloud-scripts/zkcli.sh -zkhost 127.0.0.1:9983 -cmd upconfig -confname my_new_config -confdir server/solr/configsets/basic_configs/conf
----

[[CommandLineUtilities-BootstrapZooKeeperfromexistingSOLR_HOME]]
=== Bootstrap ZooKeeper from existing SOLR_HOME

[source,bash]
----
./server/scripts/cloud-scripts/zkcli.sh -zkhost 127.0.0.1:2181 -cmd bootstrap -solrhome /var/solr/data
----

.Bootstrap with chroot
[NOTE]
====
Using the boostrap command with a zookeeper chroot in the `-zkhost` parameter, e.g. `-zkhost 127.0.0.1:2181/solr`, will automatically create the chroot path before uploading the configs.
====

[[CommandLineUtilities-PutarbitrarydataintoanewZooKeeperfile]]
=== Put arbitrary data into a new ZooKeeper file

[source,bash]
----
./server/scripts/cloud-scripts/zkcli.sh -zkhost 127.0.0.1:9983 -cmd put /my_zk_file.txt 'some data'
----

[[CommandLineUtilities-PutalocalfileintoanewZooKeeperfile]]
=== Put a local file into a new ZooKeeper file

[source,bash]
----
./server/scripts/cloud-scripts/zkcli.sh -zkhost 127.0.0.1:9983 -cmd putfile /my_zk_file.txt /tmp/my_local_file.txt
----

[[CommandLineUtilities-Linkacollectiontoaconfigurationset]]
=== Link a collection to a configuration set

[source,bash]
----
./server/scripts/cloud-scripts/zkcli.sh -zkhost 127.0.0.1:9983 -cmd linkconfig -collection gettingstarted -confname my_new_config
----

[[CommandLineUtilities-CreateanewZooKeeperpath]]
=== Create a new ZooKeeper path

This can be useful to create a chroot path in ZooKeeper before first cluster start.

[source,bash]
----
./server/scripts/cloud-scripts/zkcli.sh -zkhost 127.0.0.1:2181 -cmd makepath /solr
----


[[CommandLineUtilities-Setaclusterproperty]]
=== Set a cluster property

This command will add or modify a single cluster property in `clusterprops.json`. Use this command instead of the usual getfile -> edit -> putfile cycle.

Unlike the CLUSTERPROP command on the <<collections-api.adoc#CollectionsAPI-clusterprop,Collections API>>, this command does *not* require a running Solr cluster.

[source,bash]
----
./server/scripts/cloud-scripts/zkcli.sh -zkhost 127.0.0.1:2181 -cmd clusterprop -name urlScheme -val https
----
{'fraction_non_alphanumeric': 0.11162237207457358, 'fraction_numerical': 0.014676715589051963, 'mean_word_length': 4.817258883248731, 'pattern_counts': {'":': 0, '<': 33, '<?xml version=': 0, '>': 37, 'https://': 4, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 16, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 3, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3308980', 'n_tokens_mistral': 4070, 'n_tokens_neox': 3773, 'n_words': 1405}