Hazelcast CLC

Installation

There are two ways you can install the command line client:

• Using Brew [Recommended]
• Using script installation

Installing with Brew [Recommended]

brew tap utku-caglayan/hazelcast-clc
brew install hazelcast-commandline-client

To have a superior experience, enable autocompletion on Brew:

• For Bash users:

  • Execute brew install bash-completion and follow the printed "Caveats" section.
    Example instruction: Add the following line to your ~/.bash_profile:

     [[ -r "/home/ubuntu/.linuxbrew/etc/profile.d/bash_completion.sh" ]] && . "/home/ubuntu/.linuxbrew/etc/profile.d/bash_completion.sh"
    

    Note that paths may differ depending on your installation, so you should follow the Caveats section on your system.

• For Zsh users

  • Follow https://docs.brew.sh/Shell-Completion#configuring-completions-in-zsh

Installation with script

curl https://raw.githubusercontent.com/hazelcast/hazelcast-commandline-client/main/scripts/install.sh | bash

Uninstallation

Depending on how you install the command line client, choose the uninstallation option.

Uninstallation using Brew

brew uninstall hazelcast-commandline-client
brew untap utku-caglayan/hazelcast-clc

Uninstallation using script

~/.local/share/hz-cli/bin/uninstall.sh

Usage

Make sure a Hazelcast 4 or Hazelcast 5 cluster is running.

# Start interactive shell
hzc

# Print help
hzc --help

# Non-interactive mode
hzc map --name myMap put --key myKey --value myValue

Keyboard Shortcuts

Emacs-like keyboard shortcuts are available by default (these also are the default shortcuts in Bash shell).

Key Binding	Description
Ctrl + A	Go to the beginning of the line (Home)
Ctrl + E	Go to the end of the line (End)
Ctrl + P	Previous command (Up arrow)
Ctrl + N	Next command (Down arrow)
Ctrl + F	Forward one character
Ctrl + B	Backward one character
Ctrl + D	Delete character under the cursor
Ctrl + H	Delete character before the cursor (Backspace)
Ctrl + W	Cut the word before the cursor to the clipboard
Ctrl + K	Cut the line after the cursor to the clipboard
Ctrl + U	Cut the line before the cursor to the clipboard
Ctrl + L	Clear the screen
\
With few additions:

Key Binding	Description
Ctrl + C	Cancel running command or close the app
Ctrl + ->	Go to the end of to next word
Ctrl + <-	Go to the start of the previous word

Connecting to Hazelcast Cloud

The cluster creation and retrieving connection info can be done directly in command line using Hazelcast Cloud CLI.

• Authenticate to Hazelcast Cloud account:

  hzcloud login
  -  API Key: SAMPLE_API_KEY
  -  API Secret: SAMPLE_API_SECRET
  

• Create a cluster:

  hzcloud starter-cluster create \
  --cloud-provider=aws \
  --cluster-type=FREE \
  --name=mycluster \
  --region=us-west-2 \
  --total-memory=0.2 \
  --hazelcast-version=5.0
  
  > Cluster 2258 is creating. You can check the status using hzcloud starter-cluster list.
  

• Wait until the cluster is running:

  hzcloud starter-cluster list
  
  > 
  ┌────────┬────────────┬─────────┬─────────┬──────────────┬────────────────┬───────────┬─────────┐
  │ Id     │ Name       │ State   │ Version │ Memory (GiB) │ Cloud Provider │ Region    │ Is Free │
  ├────────┼────────────┼─────────┼─────────┼──────────────┼────────────────┼───────────┼─────────┤
  │ 2285   │ mycluster  │ PENDING │ 5.0     │          0.2 │ aws            │ us-west-2 │ true    │
  ├────────┼────────────┼─────────┼─────────┼──────────────┼────────────────┼───────────┼─────────┤
  │ Total: │ 1          │         │         │              │                │           │         │
  └────────┴────────────┴─────────┴─────────┴──────────────┴────────────────┴───────────┴─────────┘
  
  ...
  
  hzcloud starter-cluster list
  > 
  ┌────────┬────────────┬─────────┬─────────┬──────────────┬────────────────┬───────────┬─────────┐
  │ Id     │ Name       │ State   │ Version │ Memory (GiB) │ Cloud Provider │ Region    │ Is Free │
  ├────────┼────────────┼─────────┼─────────┼──────────────┼────────────────┼───────────┼─────────┤
  │ 2285   │ mycluster  │ RUNNING │ 5.0     │          0.2 │ aws            │ us-west-2 │ true    │
  ├────────┼────────────┼─────────┼─────────┼──────────────┼────────────────┼───────────┼─────────┤
  │ Total: │ 1          │         │         │              │                │           │         │
  └────────┴────────────┴─────────┴─────────┴──────────────┴────────────────┴───────────┴─────────┘
  
  

• Get the cluster name and discovery token:

  # Get cluster name
  hzcloud starter-cluster get --cluster-id 2285 --output json | jq '.releaseName'
  > "ex-1111"
  
  # Get discovery token
  hzcloud starter-cluster get --cluster-id 2285 --output json | jq '.discoveryTokens[].token'
  > "exampleHashDiscoveryToken"
  

• Connect to the cluster using the command line client using the credentials above:

  hzc --cluster-name <CLUSTER NAME> --cloud-token <DISCOVERY TOKEN>
  

SSL Configuration

You can use the following configuration file to enable SSL support:

ssl:
    enabled: true
    servername: "HOSTNAME-FOR-SERVER"
    # or: insecureskipverify: true
hazelcast:
  cluster:
    security:
      credentials:
        username: "OPTIONAL USERNAME"
        password: "OPTIONAL PASSWORD"
    name: "CLUSTER-NAME"
    network:
      addresses:
        - "localhost:5701"

Mutual authentication is also supported:

ssl:
    enabled: true
    servername: "HOSTNAME-FOR-SERVER"
    # insecureskipverify: true
    capath: "/tmp/ca.pem"
    certpath: "/tmp/cert.pem"
    keypath: "/tmp/key.pem"
    keypassword: "PASSWORD FOR THE KEY"
hazelcast:
  cluster:
    security:
      credentials:
        username: "OPTIONAL USERNAME"
        password: "OPTIONAL PASSWORD"
    name: "CLUSTER-NAME"
    network:
      addresses:
        - "localhost:5701"

Cloud SSL configuration:

ssl:
    enabled: true
    capath: "/tmp/ca.pem"
    certpath: "/tmp/cert.pem"
    keypath: "/tmp/key.pem"
    keypassword: "PASSWORD FOR THE KEY"
hazelcast:
  cluster:
    name: "CLUSTER NAME"
    cloud:
      token: "HAZELCAST CLOUD TOKEN"
      enabled: true

More examples

# Get from a map
hzc map get --name my-map --key my-key

# Put to a map
hzc map put --name my-map --key my-key --value my-value

# Get state of the cluster
hzc cluster get-state

# Work with JSON values
hzc map put --name map --key b --value-type json --value '{"english":"Greetings"}'
hzc map get --name map --key b
> {"english":"Greetings"}

# Change state of the cluster
# Either of these: active | frozen | no_migration | passive
hzc cluster change-state --state <NEW_STATE>

# Shutdown the cluster
hzc cluster shutdown

# Get the version of the cluster
hzc cluster version

Configuration

# Using Custom Config
# <CONFIG_PATH>: path of the target configuration
hzc --config <CONFIG_PATH>

# Connect to a Local Hazelcast cluster
# <ADDRESSES>: addresses of the members of the Hazelcast cluster
e.g. 192.168.1.1:5702,192.168.1.2:5703,192.168.1.3:5701
# <CLUSTER_NAME>: name of the cluster
hzc --address <ADDRESSES> --cluster-name <YOUR_CLUSTER_NAME>

Build from source

Requirements

• Go 1.15 or better
• Make

Download the repository using Git

git clone https://github.com/hazelcast/hazelcast-commandline-client.git

Then, build the project

cd hazelcast-commandline-client
make