Quickstart

Get started with the Control Plane CLI in minutes.

Follow these steps to install, authenticate, and start using the Control Plane CLI.

1. Install the CLI

   Choose your preferred installation method:

   npm

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

   npm install -g @controlplane/cli
   

   Requires Node.js version 18+ (an active LTS release is recommended).

   For detailed instructions, see Installation.

   Homebrew

   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.

   For detailed instructions, see Installation.

   Binary

   Download from the Installation page.

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:

   cpln login
   

   The CLI prints a login URL and a six-digit confirmation code, then waits. Open the URL in a browser on any device, sign in, and enter the code. The CLI stores your credentials in a default profile.

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:

List GVCs

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