Hazelcast CLC

Installation

We provide binaries for the popular platforms at our Releases page. In order to install CLC:

• Download the release package for your platform,
• Extract it,
• Optionally move the clc binary to somewhere in your PATH, so it can be run in any terminal without additional settings.

Currently we provide precompiled binaries of CLC for the following platforms and architectures:

• Linux/amd64
• Windows/amd64
• MacOS/amd64
• MacOS/arm64

Additionally, we provide an installer for Windows 10 and up. The installer can install CLC for either system-wide or just for the user. It adds the clc binary automatically to the $PATH, so it can be run in any terminal without additional settings.

On MacOS, you may need to remove the CLC binary from quarantine, if you get a security warning:

$ xattr -d com.apple.quarantine CLC_FOLDER/clc

Use the correct path instead of CLC_FOLDER in the command above.

If your platform is not one of the above, you may want to compile CLC yourself. Our build process is very simple and doesn't have many dependencies. In most cases just running make is sufficient to build CLC if you have the latest Go compiler installed. See Building from source section.

Usage Summary

Home Directory

CLC stores all configuration, logs and other files in its home directory. We will refer to that directory as $CLC_HOME. You can use clc home command to show where is $CLC_HOME:

$ clc home
/home/guest/.local/share/clc

Configuration

CLC has a simple YAML configuration, usually named config.yaml. This file can exist anywhere in the file system, and can be used with the --config (or -c) flag:

$ clc -c test/config.yaml

If there is a config.yaml in the same directory with the CLC binary and the configuration was not explicitly set, CLC tries to load that configuration file:

$ ls -lh
total 17M
-rwxrwxr-x 1 yuce yuce  17M Nov 26 23:11 clc*
-rw------- 1 yuce yuce  200 Nov 26 23:12 config.yaml

configs directory in $CLC_HOME is special, it contains all the configurations known to CLC. Known configurations can be directly specified by their names, instead of the full path. clc config list command lists the configurations known to CLC:

# List configurations
$ clc config list
default
pr-3066

# Start CLC shell with configuration named pr-3066 
$ clc -c pr-3066

If no configuration is specified, the default configuration is used if it exists.

Configuration format

All paths in the configuration are relative to the parent directory of the configuration file.

• cluster

  • name: Name of the cluster. By default dev.
  • address: Address of a member in the cluster. By default localhost:5701.
  • discovery-token: {hazelcast-cloud} Serverless discovery token.

• ssl

  • ca-path: TLS CA certificate path.
  • cert-path: TLS certificate path.
  • key-path: TLS mutual authentication key certificate path.
  • key-password: Password for the key certificate.

• log

  • path: Path to the log file, or stderr. By default, the logs are written to $CLC_HOME/logs with the current date as the name.
  • level: Log level, one of: debug, info, warn, error. The default is info.

Here's a sample {hazelcast-cloud} Serverless configuration:

cluster:
  name: "pr-3814"  
  discovery-token: "HY8eR7X...."
ssl:
  ca-path: "ca.pem"
  cert-path: "cert.pem"
  key-path: "key.pem"
  key-password: "a6..."

Logging

CLC doesn't log to the screen by default, in order to reduce clutter. By default, logs are saved in $CLC_HOME/logs, creating a new log file per day. In order to log to a different file, or to stderr (usually the screen), use the --log.path flag:

# log to object-list.log
$ clc object list --log.path object-list.log

# log to screen
$ clc object list --log.path stderr

By default, logs with level info and above are logged. You can use the --log.level flag to change the level. Supported levels: debug, info, warn, error

# log only errors
$ clc object list --log.level error

Non-interactive Mode

Run commands:

$ clc map set my-key my-value

Get help:

$ clc --help

Interactive (Shell) Mode

Start interactive shell:

$ clc

Run SQL commands:

(default)> select * from cities;

Run CLC commands:

(default)> \map set my-key my-value

Keyboard Shortcuts

The following keyboard shortcuts are available in the interactive-mode:

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
Ctrl + K	Cut the line after the cursor
Ctrl + U	Cut the line before the cursor
Ctrl + L	Clear the screen
Ctrl + C	Cancel running command

Generating auto-completion

CLC supports auto-completion in the non-interactive mode for the following shells:

• Bash
• Fish
• Powershell
• Zsh

Run clc completion SHELL-NAME command to generate an autocompletion file. The instructions for each shell is different and can be access by running clc completion SHELL-NAME --help:

# show the instructions to enable auto-completion for bash
$ clc completion bash --help

# generate the auto-completion for bash and save it to clc.bash
$ clc completion bash > clc.bash

Building from source

The following targets are tested and supported. The prior versions of the given targets would also work, but that's not tested.

• Ubuntu 22.04 or better.
• MacOS 12 or better.
• Windows 10 or better.

Requirements

• Go 1.19 or better
• Git
• GNU Make (on Linux and MacOS)
• Command Prompt or Powershell (on Windows)
• go-winres: https://github.com/tc-hib/go-winres (on Windows)

1. Download the source

You can acquire the source using Git:

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

Or download the source archive from https://github.com/hazelcast/hazelcast-commandline-client/archive/refs/heads/main.zip and extract it.

2. Build the project

$ cd hazelcast-commandline-client
$ make

The clc or clc.exe binary is created in the build directory.

Finally, run the project

CLC starts the in interactive mode by default.

On Linux and MacOS:

./build/clc

On Windows:

.\build\clc.exe