Command Line Interface (CLI)

GigaSpaces provides a CLI tool for administration and maintenance tasks. The CLI is based on the REST Manager API, enabling users to administer local, remote, and cloud-based application environments.

Use the gs script to invoke the CLI. If no arguments are specified, the usage instructions and available commands are displayed, as shown below:

If you are upgrading from a version prior to release 14.5, this is a new version of the CLI tool and uses a different syntax and command set. For more information, see Upgrading the CLI.

CLI Configuration

The CLI connects to the REST Manager API using the name or IP address of the Manager server. Configuration is applied from one of the following:

  • The first server configured in the XAP_MANAGER_SERVERS environment variable.
  • The server configured using --server command line option.
  • The localhost as the server to connect to (if none of the above was applied).

Interactive Shell

A CLI interactive shell is available for all platforms. To activate interactive mode, navigate to <XAP-HOME>/bin and type gs to display the CLI help with command usage and the available options and commands. For each command you enter, the interactive shell provides guidance by:

  • Displaying the same command help when a partial command is entered.
  • Auto-completing the command when you type the first letters of the command and press TAB.

Bash Completion

Overview

In addition to the interactive shell, the CLI provides bash completion of all commands for Linux and MacOS X users.

Linux Users

After generating and activating the auto-completion (as explained below), do the following:

  1. Navigate to <XAP-HOME>/bin.
  2. In the command window, type gs.
  3. Press TAB+TAB. This will complete the command sequence, or list all the available completions if there are multiple options.

Prerequisite for MacOS

The default 3.2 Bash shell of your Mac has basic Bash completion functionality. However, newer versions of Bash starting with 4.0 support a much more advanced type of completion, called programmable completion. Today, many completion scripts make use of new features that are not supported by Bash 3.2, and that also might depend on a third-party project called bash-completion.

To apply Bash completion on MacOS:

  1. Upgrade the Bash version on your machine to 4.0 or higher. For example, brew install bash.
  2. Install the bash-completion project on your system.
  3. When using autocomplete, type ./gs.sh and then press TAB+TAB.

You can add .gs.as an alias of .gs.shto the .bash_profile, in order to simplify using the auto-complete feature.

Generating a Completion Script

Programmable completion allows defining command-specific completion logic. This enables users to auto-complete sub-commands, options, and other arguments of commands in a context-specific manner.

A completion specification defines the applicable completions for the argument tokens of a command.

To define a completion specification:

  • Run ./gs.sh completion with one of the following options:

    Options Description Example
    --stdout Prints the completion code to standard output. ./gs.sh completion --stdout
    --target=<file> Stores the completion code in the specified file. ./gs.sh completion --target gs.completion

Activating Command Completion

Current Shell

To load the gs completion code for bash into the current shell:

  • Enter this command:

    $ source <(./gs.sh completion --stdout)

    OR

  • Use the --target option to create the completion code in a file, and then source it with a script containing these commands:

    $ ./gs.sh completion --target gs.completion
    $ source gs.completion

Each New Shell

To load the gs completion for each new shell:

  • Source this script from the .bash_profile to be loaded on each session:

    $ ./gs.sh completion --target /path/to/bash_completion.d/gs.completion

    You can also leverage bash completion behavior by placing the script in the bash_completion.d folder.

Running a Local Manager Server

To run a local Manager server and a web browser client, type gs host run-agent --auto.

To view a list of the running agents, type gs host list .