Upgrading the CLI

The new Command Line Interface, which was introduced in release 12.3, provides a simpler syntax and is cloud-friendly (based on the REST Manager API).

The legacy CLI is still supported, but has been deprecated as of GigaSpaces Platform and GigaSpaces release 14.0 and will be removed in a future version. Customers upgrading from older product versions are encouraged to upgrade to the new CLI.

To get started with the new CLI, simply run gs --help from the product's bin folder.

Setting the CLI Version

The legacy CLI that was packaged with GigaSpaces products up to and including release 12.2 is version 1. The new CLI that was introduced in release 12.3 is version 2.

Note the following changes in functionality for the CLI:

  • Until release 14.5, version 2 of the CLI was started by running either the insightedge or xap script, and version 1 (deprecated) was started by running the gs script.
  • Starting in release 14.5, running gs starts version 2 of the CLI; the insightedge and xap scripts have been deprecated and removed.
  • All the deprecated CLI scripts are available in the $GS_HOME/bin/deprecated.zip file.

Rolling Back the CLI Version

If you need to explicitly roll back the CLI in the latest GigaSpaces product to version 1, you can do this in one of the following ways:

  • Global change to version 1 - Edit the $GS_HOME/setenv-overrides script and set the GS_CLI_VERSION environment variable to 1. This option is useful if you are upgrading from an older GigaSpaces release and need to globally revert to the old syntax temporarily.

  • Per-command - Use the --cli-version option to set the CLI version for a specific command invocation, for example gs --cli-version=1 . This option overrides the GS_CLI_VERSION environment variable (if it was set). This option is useful towards the end of the upgrade process, enabling you to migrate your scripts gradually by changing one command at a time to use and test the new syntax, before moving to the next command.

Version 1 of the CLI is deprecated and will be removed in a future GigaSpaces product release. The versioning mechanism described here is provided as an aid to simplify migration, but should not be used as a long-term solution.

Updating CLI Version 2

If your scripts were already using CLI version 2 with the insightedge and xap scripts, revise them to call gs instead. As mentioned above, the deprecated-scripts.zip archive in the bin folder contains revised insightedge and xap scripts that invoke gs --cli-version=2 with the specified arguments on your behalf.

Commonly Used Options

The following table lists common tasks and the commands that are used to execute them using both the old and new Command Line Interfaces. This is not an exhaustive list, but it should help you get started with migration quickly and estimate the required effort.


Task Old Command New Command
Get help gs help gs help or gs --help
Get version gs version gs version
Get information gs stats gs info
Start agent components `gs gsa start-gsm gs host run-agent [options]
Stop agent components gs gsa shutdown [options] gs host kill-agent [options]
List agent components gs list [options] gs host list [options]
Deploy a Space gs deploy-space [options] <space-name> gs space deploy [options] <space-name>
List Spaces gs space list [options] gs space list [options]
Query a Space gs space sql [options] gs space query [options] <space-name> <type>
Deploy a Processing Unit gs deploy [options] <pu-name-or-file> gs pu deploy [options] <pu-name> <pu-file>
Undeploy a Processing Unit gs undeploy [options] <pu-name> gs pu undeploy [options] <pu-name>
Quiesce a Processing Unit gs quiesce [options] <pu-name> gs pu quiesce [options] <pu-name>
Unquiesce a Processing Unit gs unquiesce [options] <pu-name> gs pu unquiesce [options] <pu-name>

Interactive Shell Commands

The old Command Line Interface supports an interactive shell mode, and as such includes a set of shell-related commands, which are currently not supported in the new CLI as it is not interactive.

  • cd
  • dir
  • pwd
  • ls
  • set
  • login


  • pudeploy - alias for the deploy command.
  • deploy-memcached - Can be done via the deploy command.
  • deploy-rest - Can be done via the deploy command.
  • deploy-application and undeploy-application - Low usage rate, can be done via the deploy/undeploy commands and scripting.
  • jconsole - The new CLI is based on the REST protocol, so this command is misleading. Users may access the standard JConsole directly.
  • admin multicastTest - The new CLI is based on the GigaSpaces Manager, which uses unicast.