Installation

The Control Plane CLI (cpln) is available via npm, Homebrew, or direct binary download for all major operating systems.

Choose your installation method

npm
Homebrew
Binary

Install via npm if you have Node.js version 16 or later installed.

npm install -g @controlplane/cli

Requires Node.js version 16+.

Install via Homebrew on macOS or Linux.

brew tap controlplane-com/cpln && brew install cpln

If you don’t have Homebrew installed, follow the installation instructions.

Download and install the binary package for your operating system.

Download the binary

Browser
Command line

macOS (ARM64)

Download for Apple Silicon

macOS (x64)

Download for Intel Macs

Linux / WSL2

Download for Linux (x64) or for Windows (WSL2)

Windows

Download for Windows 10/11

macOS (ARM64)
macOS (x64)
Linux
Windows (PowerShell)
Windows (WSL2)

curl -LO https://storage.googleapis.com/artifacts.cpln-build.appspot.com/binaries/cpln/2322247710-3d6447e7/cpln-macos-arm64.dmg

curl -LO https://storage.googleapis.com/artifacts.cpln-build.appspot.com/binaries/cpln/2322247710-3d6447e7/cpln-macos-x64.dmg

curl -LO https://storage.googleapis.com/artifacts.cpln-build.appspot.com/binaries/cpln/2322247710-3d6447e7/cpln-linux.tgz

Invoke-WebRequest -Uri "https://storage.googleapis.com/artifacts.cpln-build.appspot.com/binaries/cpln/2322247710-3d6447e7/cpln-win.zip" -OutFile "cpln-win.zip"

curl -LO https://storage.googleapis.com/artifacts.cpln-build.appspot.com/binaries/cpln/2322247710-3d6447e7/cpln-linux.tgz

When using WSL2, download the Linux binary, not the Windows binary.

Extract and add to PATH

macOS (ARM64)
macOS (x64)
Linux
Windows
Windows (WSL2)

hdiutil attach cpln-macos-arm64.dmg && \
cp -R /Volumes/cpln-macos-arm64/cpln /Volumes/cpln-macos-arm64/docker-credential-cpln . && \
hdiutil detach /Volumes/cpln-macos-arm64 && \
sudo mv cpln docker-credential-cpln /usr/local/bin/

You’ll be prompted to enter your password. The sudo command requires administrator privileges to move files to /usr/local/bin.

hdiutil attach cpln-macos-x64.dmg && \
cp -R /Volumes/cpln-macos-x64/cpln /Volumes/cpln-macos-x64/docker-credential-cpln . && \
hdiutil detach /Volumes/cpln-macos-x64 && \
sudo mv cpln docker-credential-cpln /usr/local/bin/

You’ll be prompted to enter your password. The sudo command requires administrator privileges to move files to /usr/local/bin.

tar -xvf cpln-linux.tgz && \
sudo mv cpln docker-credential-cpln /usr/local/bin/

You’ll be prompted to enter your password. The sudo command requires administrator privileges to move files to /usr/local/bin.

Right-click cpln-win.zip and select Extract All
Choose a permanent location (e.g., C:\Program Files\cpln)
Add to PATH:
- Press Win + R, type sysdm.cpl, and press Enter
- Click the Advanced tab → Environment Variables
- Under “User variables”, select Path and click Edit
- Click New and add the directory containing cpln.exe (e.g., C:\Program Files\cpln)
- Click OK to save all dialogs
Open a new Command Prompt or PowerShell window to use cpln

tar -xvf cpln-linux.tgz && \
sudo mv cpln docker-credential-cpln /usr/local/bin/

You’ll be prompted to enter your password. The sudo command requires administrator privileges to move files to /usr/local/bin.

Browser login in WSL2: When you run cpln login, the CLI starts a local server and opens a localhost URL. This URL won’t work in your Windows browser because it points to the WSL2 instance’s localhost, not Windows.Option 1: Install Google Chrome in WSL2 (requires WSLg for GUI support):

cd /tmp
sudo wget https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb
sudo dpkg -i google-chrome-stable_current_amd64.deb
sudo apt install --fix-broken -y
sudo dpkg -i google-chrome-stable_current_amd64.deb

After installation, Chrome appears in your Windows Start menu under the distro name (e.g., Ubuntu → Google Chrome). Run cpln login, copy the localhost URL from the terminal, and paste it into your WSL2 Chrome.Option 2: Use browser-less login with a service account token. See Browser-less CLI Login.

Verify checksums

OS	File	SHA256
macOS-arm64	cpln-macos-arm64.dmg	2d62bc22e3c5c806289af76db5b2d86dbabc63c6776299f415175a93a5992efe
macOS-x64	cpln-macos-x64.dmg	34865cc02e723719c87380452be6b618377f58eaa7465b398a97b367969b19d5
Linux	cpln-linux.tgz	5fda55379dff0881f08c5f8d49ece4f3fe7eec8fc58bafacc15257fa4207746a
Windows 10/11	cpln-win.zip	1ce3c92e395ff0cd4f6a01687bdeddbb4e8d9d1af53e78b3f829e19c73b367b0

The binary package includes two executables:

cpln - The Control Plane CLI
docker-credential-cpln - Enables Docker authentication to your org’s private image registry

Verify installation

After installing with any method, confirm the CLI is installed and accessible:

cpln --version

You should see the version number printed to the console. If you see command not found, ensure the installation directory is in your PATH.

Enable shell completion (optional)

Enable tab completion for cpln commands, subcommands, and flags in your terminal:

cpln misc install-completion

Restart your terminal after installation. For non-interactive setup and supported shells, see Shell Completion.

CLI Reference

Commands

Choose your installation method

macOS (ARM64)

macOS (x64)

Linux / WSL2

Windows

Verify installation

Enable shell completion (optional)

Next steps

Quickstart

Authentication

CLI Reference

Commands

​Choose your installation method

macOS (ARM64)

macOS (x64)

Linux / WSL2

Windows

​Verify installation

​Enable shell completion (optional)

​Next steps

Quickstart

Authentication

Choose your installation method

Verify installation

Enable shell completion (optional)

Next steps