GridGain Developers Hub

GridGain CLI Tool

Overview

The GridGain 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 run it, then configure the cluster or node using the update command.

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

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:

bin/gridgain9 cluster config update "ignite.schemaSync={delayDurationMillis=500,maxClockSkewMillis=500}"
 bin/gridgain9.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:

bin/gridgain9 cluster config update ignite.security.authentication.providers.default.users=\[\{username\=newuser,displayName\=newuser,password\=\"newpassword\",passwordEncoding\=PLAIN,roles\=\[system\]\}\]
 bin/gridgain9.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:

#!/bin/bash

...

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

bin/gridgain9 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.

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.

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> --license=<pathToLicense> [--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 Physical Topology of the specified cluster, optionally in a plain format.

cluster topology logical

[--plain] [--url]

Shows 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.

Snapshot Commands

Command Parameters Description

cluster snapshot create

[--destination] [--timestamp] [--url] (--all | --tables [,<tableNames>…​] [--tables [,<tableNames>…​]]…​)

Creates a new snapshot, optionally at the indicated timestamp, optionally for the indicated cluster URL, optionally for the specified tables only, optionally at the specified destination (referred to by the path name).

cluster snapshot delete

--id [--url]

Deletes the specified snapshot, optionally for the indicated cluster URL.

cluster snapshot restore

--id [--url] [--tables [,<tableNames>…​]] [--source ]

Restores data from the specified snapshot, optionally for the indicated cluster URL, optionally for the specified tables only, optionally from the specified source (referred to by the path name).

cluster snapshot status

[--all-nodes] [--plain] [--show-tables] [--id] [--url]

Provides information about the current status of the specified snapshot, optionally for the indicated cluster URL, optionally for the specified tables only. If no snapshot ID is specified, provides information about the status of all snapshots.

Node Commands

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

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:

Command Parameters Description

recovery partitions restart

--zone [--table] [--url] [--nodes [,<nodeNames>…​]]…​ [--partitions [, <partitionIds>…​]]…​]

Restarts the indicated partitions of the specified distribution zone (if not specified, all existing partitions) on the indicated nodes.

recovery partitions reset

--zone [--table] [--url] [--partitions [, <partitionIds>…​]]…​

Resets the indicated partitions (if not specified, all existing partitions) in the indicated zones. This operation is irreversible. It can lead to data loss. Use with caution, and only when strictly necessary.

recovery partitions states

[--plain] [--url] [--partitions [, <partitionIds>…​]]…​ [--zones [, <zoneNames>…​]]…​ (--global | [--local [--nodes [,<nodeNames>…​]]…​])

Returns the 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 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 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 CMG or 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.

User and Role Commands

These commands help you manage access to the system - users and and roles.

Command Parameters Description

role create

[--url] <roleName>

Creates a new role, optionally for the indicated cluster endpoint URL. New roles do not have any privileges.

role delete

[--url] <roleName>

Deletes the specified role, optionally from the indicated cluster endpoint URL. Role with assigned privileges cannot be deleted.

role list

[--plain] [--url] [--user]

Lists roles, optionally for the indicated cluster endpoint URL, optionally filtered by user(s).

role show

[--with-privileges] [--with-users] [--url] <roleName>

Shows the role information, optionally including privileges assigned to the role and/or the users who have that role, optionally for the indicated cluster endpoint URL.

role privilege grant

[--on] [--url>] [--action[,<action>…​]]…​ --to=[,<roleName>…​] [--to [,<roleName>…​]]…​

Grants to the specified role a privilege (permission to perform the specified action on an the specified object). For more information, see User Permissions and Roles.

role privilege revoke

[--on] [--url] [--action [,<action>…​]]…​ [--from [,<roleName>…​]]…​

Revokes privilege(s) (permissions)(s) to perform the specified action on the specified object) from the role. For more information, see User Permissions and Roles.

user create

[--password] [--url] <username>

Creates a new user.

user delete

[--url] <username>

Deletes the user.

user edit

[--password] [--url] <username>

Edits user configuration.

user list

[--plain] [--url] [--role]

Provides a list of users on the server, optionally filtered by role.

user show

[--with-roles] [--url] <username>

Provides extended information about the specific user, optionally with information about roles assigned to that user.

user role assign

[--profile] [--url=<clusterUrl>] [-r [,<roleName>…​]]…​ [--to [,<username>…​]]…​

Assigns role(s) to the specified user.

user role revoke

[--profile>] [--url] [--from [,<username>…​]]…​ [-r [,<roleName>…​]]…​

Revokes role(s) from the specified user.

Data Center Replication Commands

These commands address data center replication needs.

Command Parameters Description

dcr create

[--plain] --name --source-cluster-address [--url] [--replication-nodes [,<replicationNodes>…​]]…​ [--username --password] [[--keyStorePath] [--keyStorePassword] --trustStorePath] [--trustStorePassword]] --name

Creates a replication from the source cluster to the current cluster.

dcr delete

--name [--url]

Deletes replication specified by the cluster URL and replication name.

dcr flush

--flush-point --name [--url]

Sets a replication flush point with the provided ISO time.

dcr list

[--plain] [--url]

Lists all replications for the specified cluster, along with their statuses, optionally in a plain format.

dcr start

--name [--plain] [--schema] [--url] (--all | --tables [,<tableNames>…​])

Starts or resumes the replication specified by name.

dcr stop

--name [--plain] [--schema] [--url] (--all | --tables [,<tableNames>…​])

Stops replication specified by ID.

dcr status

--name[--plain] [--url]

Shows the current status of the specific replication.

Distribution Commands

These commands address partition distribution.

Command Parameters Description

distribution reset

[--zones <zoneNames>]

Resets the algorithm state for 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.

Command Parameters Description

clear

Clears the terminal. Equivalent to cls

cls

Clears the terminal. Equivalent to clear

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.

token revoke

[--url] (--token | --username)

Revokes the JWT token. Can revoke a specific token, or all tokens for the specified user.

version

Displays the current CLI tool version.

License Commands

These commands can be used to manage the license on a running cluster.

Command Parameters Description

update

[--url] <licenseFile>

Updates the license used by the cluster with the license from the specified file.

show

[--url]

Displays the current license used by the cluster.

CLI Tool Logs

CLI tool stores extended logs for your operations. These logs contain additional information not displayed during normal operation. You can configure the directory in the following ways:

  • By setting the IGNITE_CLI_LOGS_DIR environment variable to the directory logs will be stored it.

  • By setting the $XDG_STATE_HOME environment variable to set the CLI home folder. This configuration variable follows the XDG Base Directory Specification and does not override the IGNITE_CLI_LOGS_DIR. If $XDG_STATE_HOME is set and IGNITE_CLI_LOGS_DIR is not, logs will be stored in $XDG_STATE_HOME/ignitecli/logs directory.

If neither of the above properties are set, the logs are stored in the following locations:

  • On Unix systems and MacOS, in the ~/.local/state/ignitecli/logs directory;

  • On Windows, in the %USERPROFILE%\.local\state\ignitecli\logs folder.

© 2025 GridGain Systems, Inc. All Rights Reserved. Privacy Policy | Legal Notices. GridGain® is a registered trademark of GridGain Systems, Inc.
Apache, Apache Ignite, the Apache feather and the Apache Ignite logo are either registered trademarks or trademarks of The Apache Software Foundation.

Last updated on Oct 09, 2025