docs/_docs/ignite-cli-tool.adoc - ignite-3 - Git at Google

 // Licensed to the Apache Software Foundation (ASF) under one or more
 // contributor license agreements.  See the NOTICE file distributed with
 // this work for additional information regarding copyright ownership.
 // The ASF licenses this file to You under the Apache License, Version 2.0
 // (the "License"); you may not use this file except in compliance with
 // the License.  You may obtain a copy of the License at
 //
 // http://www.apache.org/licenses/LICENSE-2.0
 //
 // Unless required by applicable law or agreed to in writing, software
 // distributed under the License is distributed on an "AS IS" BASIS,
 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 // See the License for the specific language governing permissions and
 // limitations under the License.
 = Ignite CLI Tool

 == Overview

 The Ignite CLI tool uses REST API as a communication protocol between the node and the CLI, allowing you to configure the node. By default, the CLI tool runs in the interactive mode, but you can also execute commands without entering it.

 When using the Ignite CLI tool, the arguments should be put in quotation marks, and the string should not include line breaks. For example:

 [source, bash]
 ----
 cluster config update "ignite.security.authentication.providers.basic4={type=basic,username=name,password=pass}"
 ----

 Otherwise, special POSIX characters in strings (`{` and `}` in the above command) will be handled appropriately, leading to potentially unpredictable results.

 Alternatively, you can use the backslash (`\`) to escape all special characters in your command. For example:

 [source, bash]
 ----
 cluster config update ignite.security.authentication.providers.basic4=\{type=basic,username=name,password=pass\}
 ----

 == Commands and Options

 The following commands can be executed in the interactive CLI mode.

 === CLI Commands

 These commands help you configure your CLI tool and cluster.

 [cols="1,1,3",opts="header", stripes=none]
 |===
 | Command| Parameters | Description
 | `cli config profile create` | `[--activate] [--copy-from] <profileName>` | Creates a profile with the given name, optionally by copying an existing profile, optionally activating the new profile upon creation.
 | `cli config profile activate` | `<profileName>` | Activates the profile identified by name.
 | `cli config profile list` | | Lists configuration profiles.
 | `cli config profile show` | | Gets the current profile details.
 | `cli config get` | `<key>` | Gets the value for the specified configuration key.
 | `cli config set` | `<String=String>...` | Sets configuration parameters using comma-separated input key-value pair(s).
 | `cli config show` | | Shows the currently active configuration.
 | `cli config remove` | `<key>` | Removes the specified configuration key.
 |===

 === Cluster Commands

 These commands let you manage your cluster.

 [cols="1,1,3",opts="header", stripes=none]
 |===
 | Command| Parameters | Description
 | `cluster config show` | `[--url] [<selector>]` | Shows configuration of the cluster indicated by the endpoint URL and, optionally, by a configuration path selector.
 | `cluster config update` | `[--url] <args>...` | Updates configuration of the cluster indicated by the endpoint URL with the provided argument values.
 | `cluster init` | `--name=<clusterName> [--url] [--cluster-management-group=<node name>[,<node name>...]] [--metastorage-group=<node name>[,<node name>...]] [--config=<config> \| --config-files=<file path>[,<file path>...]`| Initializes a cluster, optionally for the indicated cluster URL, optionally with Cluster Management Group and Cluster Metastorage nodes specified, with the cluster configuration optionally provided in a file or multiple files. The path to config files is resolved relative to the folder the CLI tool is started from.
 | `cluster metrics source disable` | `<srcName>` | Disables metrics from the specifies source on all nodes of the cluster.
 | `cluster metrics source enable` | `<srcName>` | Enables metrics for the specifies source on all nodes of the cluster.
 | `cluster metrics source list` | | Prints a list of metric sources for each of the cluster's nodes, along with each source's status (enabled or disabled).
 | `cluster status` | `[--url]` | Displays the detailed status of the specified cluster.
 | `cluster topology physical` | `[--plain] [--url]` | Shows [.tooltip]#Physical Topology# of the specified cluster, optionally in a plain format.
 | `cluster topology logical` | `[--plain] [--url]` | Shows [.tooltip]#Logical Topology# of the specified cluster, optionally in a plain format.
 | `cluster unit deploy` | `--path [--url] --version [--nodes [, <nodes>...]]... <id>` | Deploys the specified version of a unit, from the specified path, optionally tp specific nodes.
 | `cluster unit undeploy` | `[--url] --version <id>` | Un-deploys the specified unit version, optionally for the specified cluster.
 | `cluster unit list` | `[--plain] [--url] [--status [,<statuses>...]]... [<unitId> [--version]]` | Lists cluster's deployed units, optionally filtered by status.
 | `connect` | `[-u -p] <nodeUrl>` | Connects to the specified node, optionally with the specified user name (u) an password (p).
 | `disconnect` || Disconnects from the current cluster.
 |===

 === Node Commands

 These commands address specific node(s) in a cluster.

 [cols="1,1,3",opts="header", stripes=none]
 |===
 | Command| Parameters | Description
 | `node config show` | `[--url \| -n] [<selector>]` | Gets the specified node (n) configuration.
 |`node config update` | `[--url \| -n] <args>...` | Updates the local node configuration with the arguments in the HOCON format.
 | `node status` | `[--url \| -n]` |Shows the status of the default node, or a different one if specified.
 | `node version` | `[--url \| -n]` |Shows the node's build version.
 | `node metric list` | `[--plain][--url \| -n]` |Lists node's metrics.
 | `node metric source enable` | `[--url \| -n] <srcName>` |Enables a metric source for the node.
 | `node metric source disable` | `[--url \| -n] <srcName>` |Disables a metric source for the node.
 | `node metric source list` | `[--plain] [--url \| -n]` |Lists node metrics' sources.
 | `node unit list` | `[--plain] [--status [,<statuses>...]]...[<unitId> [--version]] [--url> \| -n]` |Lists node's deployment units.
 |===

 === Disaster Recovery Commands

 These commands enable you to:

 * Recover data partitions link:administrators-guide/disaster-recovery#disaster-scenarios-and-recovery-instructions[in a number of disaster scenarios]
 * Recover link:link:administrators-guide/system-group-recovery[system system RAFT groups]

 [cols="2,2,3",opts="header", stripes=none]
 |===
 | Command| Parameters | Description
 | `recovery partitions restart` | `--table [--url] --zone [--nodes [,<nodeNames>...]]... [--partitions [, <partitionIds>...]]...]` | Restarts the indicated partitions of the specified table (if not specified, all existing partitions) on the indicated nodes in the indicated zones.
 | `recovery partitions reset` | `--table [--url] --zone
 [--partitions [, <partitionIds>...]]...`| Resets the indicated partitions (if not specified, all existing partitions) in the indicated zones (if not specified, in all existing zones). This operation is irreversible. It can lead to data loss. Use with caution, only when strictly necessary.
 | `recovery partitions states` | `[--plain] [--url] [--partitions [, <partitionIds>...]]... [--zones [, <zoneNames>...]]... (--global \| [--local [--nodes [,<nodeNames>...]]...])`| Returns the link:administrators-guide/disaster-recovery#partition-states[partition states (local or global)], optionally for the indicated nodes and/or zones and/or partitions.
 | `recovery cluster reset` for CMG | `--url=<node-url> --cluster-management-group=<new-cmg-nodes>` | Initiates link:administrators-guide/system-group-recovery#cluster-management-group[CMG node group] repair to restore the lost majority. The command is sent to the node indicated by the `--url` parameter, which must belong to the `new-cmg-nodes` RAFT group (a comma-separated list of nodes that belong to cluster's physical topology).
 | `recovery cluster reset` for MG | `--url=<existing-node-url> [--cluster-management-group=<new-cmg-nodes>] --metastorage-replication-factor=N` | Initiates link:administrators-guide/system-group-recovery#majority-loss[MG node group] repair to restore the lost majority. `N` is the requested number of the voting RAFT nodes in the MG after repair. If you omit `--cluster-management-group`, the command takes the current CMG voting members set from the CMG leader; if CMG is not available, the command fails.
 | `recovery cluster migrate` | `--old-cluster-url=<url-of-old-cluster-node> --new-cluster-url=<url-of-new-cluster-node>` | Initiates migration of a link:administrators-guide/system-group-recovery#cluster-management-group[CMG] or link:administrators-guide/system-group-recovery#metastorage-group[MG] node that did not take part in recovery performed by `recovery cluster reset` (because it was down or unavailable due to a network partition) to the new (recovered) cluster.
 |===

 === Distribution Commands

 These commands address partition distribution.

 [cols="1,1,3",opts="header", stripes=none]
 |===
 | Command| Parameters | Description
 | `distribution reset` | `[--zones <zoneNames>]`| Resets the algorithm state for link:administrators-guide/data-partitions#distribution-reset[partition distribution] in all tables within the specified zones. Generates partition assignments "from scratch" (as if the same table (zone) was just created on the data nodes. This ensures data colocation between tables in a zone.
 |===

 === Miscellaneous Commands

 These are general-purpose commands.

 [cols="1,1,3",opts="header", stripes=none]
 |===
 | Command| Parameters | Description
 | `cls` || Clears the terminal.
 | `exit` || Stops the current interactive session.
 | `help` | `<command or command group>` | Provides information on available command groups, commands in the specified group, or for the specified command.
 | `sql` | `[--plain] [--jdbc-url] [<command> \| --file]`| Executes the specified SQL query (command) or the queries included in the specified file, on the specified cluster.
 | `version` || Displays the current CLI tool version.
 |===
	// Licensed to the Apache Software Foundation (ASF) under one or more
	// contributor license agreements. See the NOTICE file distributed with
	// this work for additional information regarding copyright ownership.
	// The ASF licenses this file to You under the Apache License, Version 2.0
	// (the "License"); you may not use this file except in compliance with
	// the License. You may obtain a copy of the License at
	//
	// http://www.apache.org/licenses/LICENSE-2.0
	//
	// Unless required by applicable law or agreed to in writing, software
	// distributed under the License is distributed on an "AS IS" BASIS,
	// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	// See the License for the specific language governing permissions and
	// limitations under the License.
	= Ignite CLI Tool

	== Overview

	The Ignite CLI tool uses REST API as a communication protocol between the node and the CLI, allowing you to configure the node. By default, the CLI tool runs in the interactive mode, but you can also execute commands without entering it.

	When using the Ignite CLI tool, the arguments should be put in quotation marks, and the string should not include line breaks. For example:

	[source, bash]
	----
	cluster config update "ignite.security.authentication.providers.basic4={type=basic,username=name,password=pass}"
	----

	Otherwise, special POSIX characters in strings (`{` and `}` in the above command) will be handled appropriately, leading to potentially unpredictable results.

	Alternatively, you can use the backslash (`\`) to escape all special characters in your command. For example:

	[source, bash]
	----
	cluster config update ignite.security.authentication.providers.basic4=\{type=basic,username=name,password=pass\}
	----

	== Commands and Options

	The following commands can be executed in the interactive CLI mode.

	=== CLI Commands

	These commands help you configure your CLI tool and cluster.

	[cols="1,1,3",opts="header", stripes=none]
	\|===
	\| Command\| Parameters \| Description
	\| `cli config profile create` \| `[--activate] [--copy-from] <profileName>` \| Creates a profile with the given name, optionally by copying an existing profile, optionally activating the new profile upon creation.
	\| `cli config profile activate` \| `<profileName>` \| Activates the profile identified by name.
	\| `cli config profile list` \| \| Lists configuration profiles.
	\| `cli config profile show` \| \| Gets the current profile details.
	\| `cli config get` \| `<key>` \| Gets the value for the specified configuration key.
	\| `cli config set` \| `<String=String>...` \| Sets configuration parameters using comma-separated input key-value pair(s).
	\| `cli config show` \| \| Shows the currently active configuration.
	\| `cli config remove` \| `<key>` \| Removes the specified configuration key.
	\|===

	=== Cluster Commands

	These commands let you manage your cluster.

	[cols="1,1,3",opts="header", stripes=none]
	\|===
	\| Command\| Parameters \| Description
	\| `cluster config show` \| `[--url] [<selector>]` \| Shows configuration of the cluster indicated by the endpoint URL and, optionally, by a configuration path selector.
	\| `cluster config update` \| `[--url] <args>...` \| Updates configuration of the cluster indicated by the endpoint URL with the provided argument values.
	\| `cluster init` \| `--name=<clusterName> [--url] [--cluster-management-group=<node name>[,<node name>...]] [--metastorage-group=<node name>[,<node name>...]] [--config=<config> \\| --config-files=<file path>[,<file path>...]`\| Initializes a cluster, optionally for the indicated cluster URL, optionally with Cluster Management Group and Cluster Metastorage nodes specified, with the cluster configuration optionally provided in a file or multiple files. The path to config files is resolved relative to the folder the CLI tool is started from.
	\| `cluster metrics source disable` \| `<srcName>` \| Disables metrics from the specifies source on all nodes of the cluster.
	\| `cluster metrics source enable` \| `<srcName>` \| Enables metrics for the specifies source on all nodes of the cluster.
	\| `cluster metrics source list` \| \| Prints a list of metric sources for each of the cluster's nodes, along with each source's status (enabled or disabled).
	\| `cluster status` \| `[--url]` \| Displays the detailed status of the specified cluster.
	\| `cluster topology physical` \| `[--plain] [--url]` \| Shows [.tooltip]#Physical Topology# of the specified cluster, optionally in a plain format.
	\| `cluster topology logical` \| `[--plain] [--url]` \| Shows [.tooltip]#Logical Topology# of the specified cluster, optionally in a plain format.
	\| `cluster unit deploy` \| `--path [--url] --version [--nodes [, <nodes>...]]... <id>` \| Deploys the specified version of a unit, from the specified path, optionally tp specific nodes.
	\| `cluster unit undeploy` \| `[--url] --version <id>` \| Un-deploys the specified unit version, optionally for the specified cluster.
	\| `cluster unit list` \| `[--plain] [--url] [--status [,<statuses>...]]... [<unitId> [--version]]` \| Lists cluster's deployed units, optionally filtered by status.
	\| `connect` \| `[-u -p] <nodeUrl>` \| Connects to the specified node, optionally with the specified user name (u) an password (p).
	\| `disconnect` \|\| Disconnects from the current cluster.
	\|===

	=== Node Commands

	These commands address specific node(s) in a cluster.

	[cols="1,1,3",opts="header", stripes=none]
	\|===
	\| Command\| Parameters \| Description
	\| `node config show` \| `[--url \\| -n] [<selector>]` \| Gets the specified node (n) configuration.
	\|`node config update` \| `[--url \\| -n] <args>...` \| Updates the local node configuration with the arguments in the HOCON format.
	\| `node status` \| `[--url \\| -n]` \|Shows the status of the default node, or a different one if specified.
	\| `node version` \| `[--url \\| -n]` \|Shows the node's build version.
	\| `node metric list` \| `[--plain][--url \\| -n]` \|Lists node's metrics.
	\| `node metric source enable` \| `[--url \\| -n] <srcName>` \|Enables a metric source for the node.
	\| `node metric source disable` \| `[--url \\| -n] <srcName>` \|Disables a metric source for the node.
	\| `node metric source list` \| `[--plain] [--url \\| -n]` \|Lists node metrics' sources.
	\| `node unit list` \| `[--plain] [--status [,<statuses>...]]...[<unitId> [--version]] [--url> \\| -n]` \|Lists node's deployment units.
	\|===

	=== Disaster Recovery Commands

	These commands enable you to:

	* Recover data partitions link:administrators-guide/disaster-recovery#disaster-scenarios-and-recovery-instructions[in a number of disaster scenarios]
	* Recover link:link:administrators-guide/system-group-recovery[system system RAFT groups]

	[cols="2,2,3",opts="header", stripes=none]
	\|===
	\| Command\| Parameters \| Description
	\| `recovery partitions restart` \| `--table [--url] --zone [--nodes [,<nodeNames>...]]... [--partitions [, <partitionIds>...]]...]` \| Restarts the indicated partitions of the specified table (if not specified, all existing partitions) on the indicated nodes in the indicated zones.
	\| `recovery partitions reset` \| `--table [--url] --zone
	[--partitions [, <partitionIds>...]]...`\| Resets the indicated partitions (if not specified, all existing partitions) in the indicated zones (if not specified, in all existing zones). This operation is irreversible. It can lead to data loss. Use with caution, only when strictly necessary.
	\| `recovery partitions states` \| `[--plain] [--url] [--partitions [, <partitionIds>...]]... [--zones [, <zoneNames>...]]... (--global \\| [--local [--nodes [,<nodeNames>...]]...])`\| Returns the link:administrators-guide/disaster-recovery#partition-states[partition states (local or global)], optionally for the indicated nodes and/or zones and/or partitions.
	\| `recovery cluster reset` for CMG \| `--url=<node-url> --cluster-management-group=<new-cmg-nodes>` \| Initiates link:administrators-guide/system-group-recovery#cluster-management-group[CMG node group] repair to restore the lost majority. The command is sent to the node indicated by the `--url` parameter, which must belong to the `new-cmg-nodes` RAFT group (a comma-separated list of nodes that belong to cluster's physical topology).
	\| `recovery cluster reset` for MG \| `--url=<existing-node-url> [--cluster-management-group=<new-cmg-nodes>] --metastorage-replication-factor=N` \| Initiates link:administrators-guide/system-group-recovery#majority-loss[MG node group] repair to restore the lost majority. `N` is the requested number of the voting RAFT nodes in the MG after repair. If you omit `--cluster-management-group`, the command takes the current CMG voting members set from the CMG leader; if CMG is not available, the command fails.
	\| `recovery cluster migrate` \| `--old-cluster-url=<url-of-old-cluster-node> --new-cluster-url=<url-of-new-cluster-node>` \| Initiates migration of a link:administrators-guide/system-group-recovery#cluster-management-group[CMG] or link:administrators-guide/system-group-recovery#metastorage-group[MG] node that did not take part in recovery performed by `recovery cluster reset` (because it was down or unavailable due to a network partition) to the new (recovered) cluster.
	\|===

	=== Distribution Commands

	These commands address partition distribution.

	[cols="1,1,3",opts="header", stripes=none]
	\|===
	\| Command\| Parameters \| Description
	\| `distribution reset` \| `[--zones <zoneNames>]`\| Resets the algorithm state for link:administrators-guide/data-partitions#distribution-reset[partition distribution] in all tables within the specified zones. Generates partition assignments "from scratch" (as if the same table (zone) was just created on the data nodes. This ensures data colocation between tables in a zone.
	\|===

	=== Miscellaneous Commands

	These are general-purpose commands.

	[cols="1,1,3",opts="header", stripes=none]
	\|===
	\| Command\| Parameters \| Description
	\| `cls` \|\| Clears the terminal.
	\| `exit` \|\| Stops the current interactive session.
	\| `help` \| `<command or command group>` \| Provides information on available command groups, commands in the specified group, or for the specified command.
	\| `sql` \| `[--plain] [--jdbc-url] [<command> \\| --file]`\| Executes the specified SQL query (command) or the queries included in the specified file, on the specified cluster.
	\| `version` \|\| Displays the current CLI tool version.
	\|===