Skip to main content
Follow these steps to install, authenticate, and start using the Control Plane CLI.
1

Install the CLI

Choose your preferred installation method:
Install via npm if you have Node.js version 16 or later installed.
npm install -g @controlplane/cli
Requires Node.js version 16+.
For detailed instructions, see Installation.
2

Verify the installation

Confirm the CLI is installed and accessible:
cpln --version
You should see the CLI version number.
3

Authenticate

Log in to Control Plane using your browser:
cpln login
This opens your browser for authentication and creates a default profile.
If you can’t use a browser, see the browser-less login guide.
When you run cpln login in WSL2, the localhost URL won’t work in your Windows browser because it points to the WSL2 instance, not Windows.Solution: Install a browser in WSL2 (requires WSLg):
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.Alternative: Use browser-less login with a service account token.
4

Explore available commands

Use the built-in help to discover commands:
cpln --help
cpln <command> --help
Start with read-only commands like cpln gvc get or cpln workload get.

​
Try your first commands

Once authenticated, try these safe, read-only commands: 
cpln gvc get

​
Deploy your first app

Build and deploy a local application to Control Plane:
1

Create a GVC

Create a Global Virtual Cloud to host your workload:
cpln gvc create --name my-app-gvc --location aws-us-east-1
2

Build and push your image

From your project directory, build and push to your org’s private registry:
cpln image build --name my-app:v1 --push
No Dockerfile? The CLI can auto-detect your language and build with buildpacks.
3

Create a workload

Deploy your image as a workload:
cpln workload create --name my-app --gvc my-app-gvc \
  --image //image/my-app:v1 --port 8080 --public
Replace 8080 with the port your application listens on. Use --public to make it accessible from the internet.
4

Check your deployment

View your workload status:
cpln workload get my-app --gvc my-app-gvc
Once ready, access your app at the endpoint shown in the output.
For more image operations, see the Images guide.

​
Next steps

Images

Build, push, and manage container images

Profiles

Manage authentication and context

Common Options

Learn about shared CLI flags

CI/CD

Use the CLI in automation