Skip to main content
The Control Plane CLI (cpln) provides a powerful command-line interface for managing organizations, GVCs, workloads, and all supporting resources.
Nearly everything you can do through the Console UI, API, or Terraform can also be done through the CLI. The CLI also provides powerful operations not available elsewhere, such as port forwarding, executing commands in containers, and converting Kubernetes manifests.

​
Get started

Installation

Install via npm, Homebrew, or binary download

Quickstart

Get up and running in minutes

Authentication

Log in with interactive or token-based flows

Profiles

Manage multiple environments and contexts

​
Quick reference

1

Install the CLI

npm install -g @controlplane/cli
2

Verify installation

cpln --version
3

Authenticate

cpln login
For browser-less environments, see Authentication.
4

Explore commands

cpln --help
cpln <command> --help
Browse all commands in the Commands section.

​
Using the CLI

Getting Help

Use built-in help to discover commands and flags

Common Options

Shared flags across all CLI commands

Output Formats

Control command output with JSON, YAML, and more

Troubleshooting

Common issues and solutions

Shell Completion

Enable tab completion for commands and flags

Common Workflows

Deploy apps, manage secrets, debug workloads, and more

​
CI/CD & automation

CI/CD Usage

Automate deployments with service accounts

Container Images

Run the CLI inside Docker containers

​
CLI-only features

These operations are unique to the CLI and provide capabilities not available in the Console or API:

cpln apply / delete

GitOps-style resource management from YAML/JSON files

cpln convert

Convert Kubernetes manifests to Control Plane format

cpln helm

Deploy Helm charts directly to Control Plane

cpln stack

Deploy Docker Compose applications to Control Plane

cpln operator

Manage the Kubernetes operator for Control Plane

cpln port-forward

Forward local ports to workloads for debugging

cpln cp

Copy files to and from workload containers

cpln workload exec

Execute commands inside running containers

cpln workload connect

Open an interactive shell in a workload container

cpln image push

Push images to Control Plane registry

docker pull

Pull images from Control Plane registry

cpln image copy

Copy images between registries or orgs
Dive into all CLI-only features in the Guides section for detailed walkthroughs and examples.

​
Common workflows

Learn by example with these common CLI workflows:
These examples assume you have a profile configured with a default org set.
Build and push your local application to Control Plane’s image registry:
bash
# Create a GVC
cpln gvc create --name my-app-gvc --location aws-us-east-1

# Build and push your image
cpln image build --name my-app:v1.0.0 --push

# Create a workload using your image
cpln workload create \
  --name my-app \
  --gvc my-app-gvc \
  --image //image/my-app:v1.0.0 \
  --port 8080 \
  --public

# View workload status
cpln workload get my-app --gvc my-app-gvc
The --port 8080 must match the port your application exposes in its Dockerfile. Change this value to match your application’s exposed port.
See Create Workload for detailed steps.
bash
# Export existing resources
cpln gvc get my-gvc --output yaml-slim > gvc.yaml
cpln workload get my-app --gvc my-gvc --output yaml-slim > workload.yaml

# Edit files, then apply
cpln apply --file gvc.yaml
cpln apply --file workload.yaml --gvc my-gvc
See cpln apply for GitOps workflows.
Create a secret, grant a workload identity access to it via a policy, and inject it as an environment variable.
bash
# Create a file containing the secret value
echo "hello-world" > my-db-password.txt

# Create an opaque secret from the file
cpln secret create-opaque --name db-password \
  --encoding plain \
  --file my-db-password.txt

# Create a GVC
cpln gvc create --name my-gvc --location aws-us-east-1

# Create an identity for your workload
cpln identity create --name my-app-identity --gvc my-gvc

# Create a policy targeting the secret
cpln policy create --name my-app-secrets-policy \
  --target-kind secret \
  --resource db-password

# Add a binding to grant the identity reveal permission
cpln policy add-binding my-app-secrets-policy \
  --identity //gvc/my-gvc/identity/my-app-identity \
  --permission reveal

# Create a workload with the identity attached and inject the secret as an env var
cpln workload create \
  --name my-app \
  --gvc my-gvc \
  --image nginx:latest \
  --port 80 \
  --identity my-app-identity \
  --env DB_PASSWORD=cpln://secret/db-password.payload \
  --public

# Check workload status (and wait for the workload to become ready)
cpln workload get my-app --gvc my-gvc

# Verify the secret is available in the container
cpln workload exec my-app --gvc my-gvc -- env | grep DB_PASSWORD

# Expected output from the cpln workload exec command
Defaulting to location 'aws-us-east-1' because no location was specified in the command.
Defaulting to replica 'my-app-00001-deployment-6d67547b5d-586d9' because no replica was specified in the command.
Defaulting to container 'nginx' because no container was specified in the command.
DB_PASSWORD=hello-world
See Policy for access control.
bash
# Build and push
cpln image build --name my-app:v1.0.0 --push

# Update workload to use new image (replace <container-name>
# with the acutal container name from your workload)
cpln workload update my-app --gvc my-gvc \
  --set spec.containers.<container-name>.image=//image/my-app:v1.0.0
See Push Image for details.
# View logs
cpln logs '{gvc="my-gvc", workload="my-app"}'

# Execute commands in a container
cpln workload exec my-app --gvc my-gvc -- ls -a

# Forward a port for local testing
cpln port-forward my-app 8080:8080 --gvc my-gvc

# Copy files from a workload (assuming your workload is using nginx:latest image)
cpln cp my-app:usr/share/nginx/html/index.html ./index.html --gvc my-gvc
See Workload Exec and Port Forward.

​
Command categories

The CLI organizes commands by resource type. Explore the Commands section for detailed reference on each command.

​
Infrastructure

gvc

Global Virtual Clouds

location

Available locations

org

Organizations

​
Workloads & compute

workload

Manage workloads

mk8s

Managed Kubernetes

volumeset

Persistent volumes

​
Images & containers

image

Container images

stack

Docker Compose stacks

​
Security & access

secret

Secrets management

policy

Access policies

identity

Workload identities

​
Users & accounts

user

User accounts

group

User groups

serviceaccount

Service accounts

​
Networking & domains

domain

Custom domains

ipset

IP sets for firewall rules

​
Infrastructure as code

apply

Create/update from files

delete

Delete from files

convert

Convert K8s to Control Plane

​
Operations & utilities

logs

View logs

port-forward

Forward ports to workloads

cp

Copy files to/from workloads

helm

Manage Helm releases

​
Cloud & integrations

cloudaccount

Cloud provider accounts

agent

Control Plane agents

auditctx

Audit contexts

​
System & admin

profile

CLI profiles

login

Authentication

quota

Resource quotas

task

Pending tasks

misc

Miscellaneous utilities

rest

Direct REST API access

​
Additional resources

API Reference

REST API documentation

Concepts

Core platform concepts

Terraform Provider

Infrastructure as code with Terraform

​
Get help

Built-in Help

Use cpln --help to explore commands

Troubleshooting

Solutions to common issues