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

npm update -g @controlplane/cli

Requires Node.js version 16+.

Install via Homebrew on macOS or Linux.

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

brew upgrade 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/2708952122-4bc72557/cpln-macos-arm64.dmg

curl -LO https://storage.googleapis.com/artifacts.cpln-build.appspot.com/binaries/cpln/2708952122-4bc72557/cpln-macos-x64.dmg

curl -LO https://storage.googleapis.com/artifacts.cpln-build.appspot.com/binaries/cpln/2708952122-4bc72557/cpln-linux.tgz

wget https://storage.googleapis.com/artifacts.cpln-build.appspot.com/binaries/cpln/2708952122-4bc72557/cpln-linux.tgz

Invoke-WebRequest -Uri "https://storage.googleapis.com/artifacts.cpln-build.appspot.com/binaries/cpln/2708952122-4bc72557/cpln-win.zip" -OutFile "cpln-win.zip"

curl -LO https://storage.googleapis.com/artifacts.cpln-build.appspot.com/binaries/cpln/2708952122-4bc72557/cpln-linux.tgz

wget https://storage.googleapis.com/artifacts.cpln-build.appspot.com/binaries/cpln/2708952122-4bc72557/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.

Logging in from WSL2: No browser is needed inside WSL2. cpln login prints a login URL and a confirmation code, so you can paste the URL into your Windows browser, sign in, and enter the code. The CLI running in WSL2 picks up the credentials on its own.

Verify checksums

OS	File	SHA256
macOS-arm64	cpln-macos-arm64.dmg	14d84014fe0cf18fc6242bc50dc2e6c0aea67792d4ac9daef791a9363b8c0965
macOS-x64	cpln-macos-x64.dmg	f1ddf131bad43aab2d66304476ebf09b945e73fbed022bc717f45dab46aaa6e3
Linux	cpln-linux.tgz	c3dbe36a03f118d4f085cf5523eb1a94ac9db54080e9ddd31f4ba150101f9fe2
Windows 10/11	cpln-win.zip	83596906d67c1236060f2851e4f71601ef8aa676392c4320f0ad742d6aa088e2

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. cpln version and cpln -v are aliases for cpln --version.

Keep the CLI up to date

Run cpln upgrade to upgrade the CLI to the latest version.

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

Keep the CLI up to date

Enable shell completion (optional)

Next steps

Quickstart

Authentication

​Choose your installation method

macOS (ARM64)

macOS (x64)

Linux / WSL2

Windows

​Verify installation

​Keep the CLI up to date

​Enable shell completion (optional)

​Next steps

Quickstart

Authentication

Choose your installation method

Verify installation

Keep the CLI up to date

Enable shell completion (optional)

Next steps