> ## Documentation Index > Fetch the complete documentation index at: https://docs.controlplane.com/llms.txt > Use this file to discover all available pages before exploring further. # CLI Reference > Comprehensive guide to the Control Plane CLI for managing infrastructure, workloads, and resources. 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. Working with an AI assistant? The [Control Plane AI Plugin](/mcp/ai-plugin) teaches Claude Code, Codex, and Gemini CLI how to drive `cpln` correctly — including the resource command map, hallucination traps, and the multi-step workflows that the CLI doesn't bundle into single commands. ## Get started Install via npm, Homebrew, or binary download Get up and running in minutes Log in with interactive or token-based flows Manage multiple environments and contexts ## Quick reference ```bash theme={null} npm install -g @controlplane/cli ``` ```bash theme={null} brew tap controlplane-com/cpln && brew install cpln ``` Download from the [Installation page](/cli-reference/installation). ```bash theme={null} cpln --version ``` ```bash theme={null} cpln login ``` For browser-less environments, see [Authentication](/cli-reference/get-started/authentication). ```bash theme={null} cpln --help cpln --help ``` Browse all commands in the **Commands** section. ## Using the CLI Use built-in help to discover commands and flags Shared flags across all CLI commands Control command output with JSON, YAML, and more Common issues and solutions Enable tab completion for commands and flags Deploy apps, manage secrets, debug workloads, and more ## CI/CD & automation Automate deployments with service accounts 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: GitOps-style resource management from YAML/JSON files Convert Kubernetes manifests to Control Plane format Deploy Helm charts directly to Control Plane Deploy Docker Compose applications to Control Plane Manage the Kubernetes operator for Control Plane Forward local ports to workloads for debugging Copy files to and from workload containers Execute commands inside running containers Open an interactive shell in a workload container Push images to Control Plane registry Pull images from Control Plane registry 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](/cli-reference/get-started/profiles) with a default org set. Build and push your local application to Control Plane's image registry: ```bash bash theme={null} # 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. Deploy using a public image from Docker Hub or another registry: ```bash bash theme={null} # Create a GVC cpln gvc create --name my-app-gvc --location aws-us-east-1 # Create a workload with a public image cpln workload create \ --name my-app \ --gvc my-app-gvc \ --image nginx:latest \ --port 80 \ --public # View workload status cpln workload get my-app --gvc my-app-gvc ``` See [Create Workload](/cli-reference/commands/workload#workload-create) for detailed steps. ```bash bash theme={null} # 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](/guides/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 bash theme={null} # 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](/reference/policy) for access control. ```bash bash theme={null} # Build and push cpln image build --name my-app:v1.0.0 --push # Update workload to use new image (replace # with the acutal container name from your workload) cpln workload update my-app --gvc my-gvc \ --set spec.containers..image=//image/my-app:v1.0.0 ``` See [Push Image](/guides/push-image) for details. ```bash theme={null} # 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](/guides/cli/workload/exec) and [Port Forward](/guides/cli/cpln-port-forward). ## Command categories The CLI organizes commands by resource type. Explore the **Commands** section for detailed reference on each command. ### Infrastructure Global Virtual Clouds Available locations Organizations ### Workloads & compute Manage workloads Managed Kubernetes Persistent volumes ### Images & containers Container images Docker Compose stacks ### Security & access Secrets management Access policies Workload identities ### Users & accounts User accounts User groups Service accounts ### Networking & domains Custom domains IP sets for firewall rules ### Infrastructure as code Create/update from files Delete from files Convert K8s to Control Plane ### Operations & utilities View logs Forward ports to workloads Copy files to/from workloads Manage Helm releases ### Cloud & integrations Cloud provider accounts Control Plane agents Audit contexts ### System & admin CLI profiles Authentication Resource quotas Pending tasks Miscellaneous utilities Direct REST API access ## Additional resources REST API documentation Core platform concepts Infrastructure as code with Terraform ## Get help Use `cpln --help` to explore commands Solutions to common issues