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 communicates with the cluster via the REST API, allowing you to configure the entire cluster or apply node-specific settings.  You can run the CLI either in the interactive mode or execute commands without entering it.

 === Interactive CLI Mode

 To use the CLI in the interactive mode, first link:quick-start/getting-started-guide#start-the-ignite-cli[run] it, then configure the link:administrators-guide/config/cluster-config[cluster] or link:administrators-guide/config/node-config[node] using the `update` command.

 For example, to add a new user to the cluster:

 [source, bash]
 ----
 cluster config update ignite.security.authentication.providers.default.users=[{username=newuser,displayName=newuser,password="newpassword",passwordEncoding=PLAIN,roles=[system]}]
 ----

 === Non-Interactive CLI Mode

 Non-interactive mode is useful for quick updates or when running commands in scripts.

 When running commands non-interactively, enclose arguments in quotation marks to ensure that special POSIX characters (such as `{` and `}`) are interpreted correctly:

 [tabs]
 --
 tab:Linux[]
 [source, bash]
 ----
 bin/ignite3 cluster config update "ignite.schemaSync={delayDurationMillis=500,maxClockSkewMillis=500}"
 ----

 tab:Windows[]
 [source, bash]
 ----
  bin/ignite3.bat cluster config update "ignite.schemaSync={delayDurationMillis=500,maxClockSkewMillis=500}"
 ----
 --

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

 [tabs]
 --
 tab:Linux[]
 [source, bash]
 ----
 bin/ignite3 cluster config update ignite.security.authentication.providers.default.users=\[\{username\=newuser,displayName\=newuser,password\=\"newpassword\",passwordEncoding\=PLAIN,roles\=\[system\]\}\]
 ----

 tab:Windows[]
 [source, bash]
 ----
  bin/ignite3.bat cluster config update ignite.security.authentication.providers.default.users=\[\{username\=newuser,displayName\=newuser,password\=\"newpassword\",passwordEncoding\=PLAIN,roles\=\[system\]\}\]
 ----
 --

 Non-interactive mode is also useful in automation scripts. For example, you can set configuration items in a Bash script as follows:

 [source, bash]
 ----
 #!/bin/bash

 ...

 bin/ignite3 cluster config update "ignite.schemaSync={delayDurationMillis=500,maxClockSkewMillis=500}"

 bin/ignite3 cluster config update "ignite.security.authentication.providers.default.users=[{username=newuser,displayName=newuser,password=\"newpassword\",passwordEncoding=PLAIN,roles=[system]}]"
 ----

 == 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. Note that `clusterName` parameter is required for successful initialization. Optionally, you can specify a cluster URL, Cluster Management Group nodes, and Metastorage nodes. You may also provide cluster configuration from one or more files. File path is resolved relative to the directory where 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 in a number of link:administrators-guide/disaster-recovery#disaster-scenarios-and-recovery-instructions[disaster scenarios]
 * Recover link:link:administrators-guide/system-groups-recovery[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-groups-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-groups-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-groups-recovery#cluster-management-group[CMG] or link:administrators-guide/system-groups-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 communicates with the cluster via the REST API, allowing you to configure the entire cluster or apply node-specific settings. You can run the CLI either in the interactive mode or execute commands without entering it.

	=== Interactive CLI Mode

	To use the CLI in the interactive mode, first link:quick-start/getting-started-guide#start-the-ignite-cli[run] it, then configure the link:administrators-guide/config/cluster-config[cluster] or link:administrators-guide/config/node-config[node] using the `update` command.

	For example, to add a new user to the cluster:

	[source, bash]
	----
	cluster config update ignite.security.authentication.providers.default.users=[{username=newuser,displayName=newuser,password="newpassword",passwordEncoding=PLAIN,roles=[system]}]
	----

	=== Non-Interactive CLI Mode

	Non-interactive mode is useful for quick updates or when running commands in scripts.

	When running commands non-interactively, enclose arguments in quotation marks to ensure that special POSIX characters (such as `{` and `}`) are interpreted correctly:

	[tabs]
	--
	tab:Linux[]
	[source, bash]
	----
	bin/ignite3 cluster config update "ignite.schemaSync={delayDurationMillis=500,maxClockSkewMillis=500}"
	----

	tab:Windows[]
	[source, bash]
	----
	bin/ignite3.bat cluster config update "ignite.schemaSync={delayDurationMillis=500,maxClockSkewMillis=500}"
	----
	--

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

	[tabs]
	--
	tab:Linux[]
	[source, bash]
	----
	bin/ignite3 cluster config update ignite.security.authentication.providers.default.users=\[\{username\=newuser,displayName\=newuser,password\=\"newpassword\",passwordEncoding\=PLAIN,roles\=\[system\]\}\]
	----

	tab:Windows[]
	[source, bash]
	----
	bin/ignite3.bat cluster config update ignite.security.authentication.providers.default.users=\[\{username\=newuser,displayName\=newuser,password\=\"newpassword\",passwordEncoding\=PLAIN,roles\=\[system\]\}\]
	----
	--

	Non-interactive mode is also useful in automation scripts. For example, you can set configuration items in a Bash script as follows:

	[source, bash]
	----
	#!/bin/bash

	...

	bin/ignite3 cluster config update "ignite.schemaSync={delayDurationMillis=500,maxClockSkewMillis=500}"

	bin/ignite3 cluster config update "ignite.security.authentication.providers.default.users=[{username=newuser,displayName=newuser,password=\"newpassword\",passwordEncoding=PLAIN,roles=[system]}]"
	----

	== 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. Note that `clusterName` parameter is required for successful initialization. Optionally, you can specify a cluster URL, Cluster Management Group nodes, and Metastorage nodes. You may also provide cluster configuration from one or more files. File path is resolved relative to the directory where 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 in a number of link:administrators-guide/disaster-recovery#disaster-scenarios-and-recovery-instructions[disaster scenarios]
	* Recover link:link:administrators-guide/system-groups-recovery[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-groups-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-groups-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-groups-recovery#cluster-management-group[CMG] or link:administrators-guide/system-groups-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.
	\|===