KubeBlocks Command Line (kbcli)

kbcli is the official command-line tool for managing KubeBlocks clusters. It provides:

Cluster lifecycle management (create, scale, delete)
Configuration and troubleshooting tools
Version compatibility checks
Shell auto-completion support

Prerequisites

Before installing kbcli, ensure your system meets these requirements:

All platforms:
- Network access to download packages
- Administrator/sudo privileges
Windows:
- PowerShell 5.0 or later
macOS/Linux:
- curl or wget installed
- Homebrew (for macOS brew installation)

Install kbcli

Supported Platforms

kbcli is available for:

macOS (Intel and Apple Silicon)
Windows (x86-64)
Linux (x86-64 and ARM64)

Choose your preferred installation method:

curl (recommended for most users)
Homebrew (macOS package manager)

Option 1: Install with curl

To install the latest stable version:

curl -fsSL https://kubeblocks.io/installer/install_cli.sh | bash

To install a specific version:

Check the available versions in kbcli Release.

Specify a version with -s and run the command below.

curl -fsSL https://kubeblocks.io/installer/install_cli.sh | bash -s <VERSION>

NOTE

Version Compatibility

Always match kbcli version with your KubeBlocks deployment
Latest stable is recommended for new installations
Existing deployments require version matching:
- KubeBlocks v1.0.0 → kbcli v1.0.x
- KubeBlocks v0.9.x → kbcli v0.9.x
Mismatches may cause operational issues

Run kbcli version to check the version of kbcli and ensure that it is successfully installed.

TIP

Troubleshooting If installation fails:

Verify network connectivity
Check firewall/proxy settings

Option 2: Install with Homebrew

Install ApeCloud tap, the Homebrew package of ApeCloud.
```
brew tap apecloud/tap
```

Install kbcli.

brew install kbcli

If you want to install kbcli with a specified version, run the commands below.

# View the available version
brew search kbcli

# Specify a version
brew install kbcli@<VERSION>

Verify that kbcli is successfully installed.
```
kbcli -h
```

Choose your preferred installation method:

Option 1: Script Installation (Recommended)

NOTE

By default, the script will be installed at C:\Program Files\kbcli-windows-amd64 and cannot be modified.

If you need to customize the installation path, use the zip file.

Run PowerShell as an administrator and execute Set-ExecutionPolicy Unrestricted.
Install kbcli.

The following script will automatically install the environment variables at C:\Program Files\kbcli-windows-amd64.
```
powershell -Command " & ([scriptblock]::Create((iwr https://www.kubeblocks.io/installer/install_cli.ps1)))"
```
To install a specified version of kbcli, use -v after the command and describe the version you want to install.
```
powershell -Command " & ([scriptblock]::Create((iwr https://www.kubeblocks.io/installer/install_cli.ps1))) -v 0.5.2"
```

Option 2: Manual Installation

Download the kbcli installation zip package from kbcli Release.
Extract the file and add it to the environment variables.
1. Click the Windows icon and select System Settings.
2. Click Settings -> Related Settings -> Advanced system settings.
3. Click Environment Variables on the Advanced tab.
4. Click New to add the path of the kbcli installation package to the user and system variables.
5. Click Apply and OK.

Install using curl:

Install kbcli.

curl -fsSL https://kubeblocks.io/installer/install_cli.sh | bash

To install a specific version:

Check the available versions in kbcli Release.

Specify a version with -s and run the command below.

curl -fsSL https://kubeblocks.io/installer/install_cli.sh | bash -s <VERSION>

Run kbcli version to check the version of kbcli and ensure that it is successfully installed.

NOTE

If a timeout exception occurs during installation, please check your network settings and retry.

Uninstallation

To completely remove kbcli and its configuration:

For curl, run

sudo rm /usr/local/bin/kbcli

For brew, run

brew uninstall kbcli

kbcli creates a hidden folder named ~/.kbcli under the HOME directory to store configuration information and temporary files. You can delete this folder after uninstalling kbcli.

Go to the kbcli installation path and delete the installation folder.
- If you install kbcli by script, go to C:\Program Files and delete the kbcli-windows-amd64 folder.
- If you customize the installation path, go to your specified path and delete the installation folder.
Delete the environment variable.
1. Click the Windows icon and click System.
2. Go to Settings -> Related Settings -> Advanced system settings.
3. On the Advanced tab, click Environment Variables.
4. Double-click Path in User variables or System variables list.
  - If you install kbcli by script, double-click Path in User variables.
  - If you customize the installation path, double-click Path based on where you created the variable before.
5. Select C:\Program Files\kbcli-windows-amd64 or your customized path and delete it. This operation requires double confirmation.
Delete a folder named .kbcli.

kbcli creates a folder named .kbcli under the C:\Users\username directory to store configuration information and temporary files. You can delete this folder after uninstalling kbcli.

Uninstall kbcli using the curl command.

sudo rm /usr/local/bin/kbcli

kbcli creates a hidden folder named ~/.kbcli under the HOME directory to store configuration information and temporary files. You can delete this folder after uninstalling kbcli.

Shell Auto-completion

kbcli provides command completion for:

bash
zsh
fish
PowerShell

# Configure SHELL-TYPE as one type from bash, fish, PowerShell, and zsh
kbcli completion SHELL-TYPE -h

For example, enable kbcli auto-completion for zsh.

Steps:

Check the user guide.
```
kbcli completion zsh -h
```
Enable the completion function of your terminal first.
```
echo "autoload -U compinit; compinit" >> ~/.zshrc
```

Enable the kbcli automatic completion function.

echo "source <(kbcli completion zsh); compdef _kbcli kbcli" >> ~/.zshrc