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

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

CI/CD & automation

CLI-only features

These operations are unique to the CLI and provide capabilities not available in the Console or API:
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

Workloads & compute

Images & containers

Security & access

Users & accounts

Networking & domains

Infrastructure as code

Operations & utilities

Cloud & integrations

System & admin

Additional resources

Get help