Using the CLI in Containers

Install the Control Plane CLI inside container images to use it in CI jobs, Cron Workloads, or custom automation containers.

When to use this

Install cpln in a container image for:

CI/CD jobs - Run cpln commands in containerized pipelines
Cron Workloads - Execute automation tasks in Control Plane cron workloads
Custom automation images - Bundle cpln with your tools and scripts

Never bake credentials into container images. Pass tokens at runtime via environment variables or secret managers.

Installation methods

npm (Node.js base)
Binary (lightweight)

Use this method if your base image already includes Node.js (16 or later).

Dockerfile

FROM node:20-slim

# Pin the CLI version for reproducible builds
ARG CPLN_CLI_VERSION=3.7.5

# Install the Control Plane CLI
RUN npm install -g @controlplane/cli@${CPLN_CLI_VERSION} && \
    cpln --version

WORKDIR /app

# Keep container running for testing (remove in production)
CMD ["tail", "-f", "/dev/null"]

Build and run:

bash

# Build the image
docker build -t cpln-test .

# Run in a container
docker run -d --name cpln-test \
  -e CPLN_TOKEN="$CPLN_TOKEN" \
  -e CPLN_ORG="my-org" \
  -e CPLN_GVC="my-gvc" \
  cpln-test

Exec into the container:

bash

docker exec -it cpln-test bash

Test the CLI:

bash

# List all workloads
cpln workload get

Cleanup:

bash

docker stop cpln-test && docker rm cpln-test

Use this method for minimal images without Node.js.

Dockerfile

# Stage 1: Download and extract the CLI
FROM debian:bookworm-slim AS cpln-downloader

# Pin the CLI version for reproducible builds
ARG CPLN_BINARY_URL=https://storage.googleapis.com/artifacts.cpln-build.appspot.com/binaries/cpln/2650573345-9851fb16/cpln-linux.tgz

# Download and extract cpln binary
RUN apt-get update && apt-get install -y --no-install-recommends curl ca-certificates && \
    curl -fsSL "${CPLN_BINARY_URL}" -o /tmp/cpln.tgz && \
    tar -xzf /tmp/cpln.tgz -C /usr/local/bin && \
    rm -rf /var/lib/apt/lists/*

# Stage 2: Runtime image
FROM debian:bookworm-slim

# Copy binaries from downloader stage
COPY --from=cpln-downloader /usr/local/bin/cpln /usr/local/bin/cpln
COPY --from=cpln-downloader /usr/local/bin/docker-credential-cpln /usr/local/bin/docker-credential-cpln

# Verify installation
RUN cpln --version

WORKDIR /work

# Keep container running for testing (remove in production)
CMD ["tail", "-f", "/dev/null"]

Build and run:

bash

# Build the image (use --platform for Apple Silicon Macs)
docker build --platform linux/amd64 -t cpln-test .

# Run in a container
docker run -d --name cpln-test \
  -e CPLN_TOKEN="$CPLN_TOKEN" \
  -e CPLN_ORG="my-org" \
  -e CPLN_GVC="my-gvc" \
  cpln-test

The --platform linux/amd64 flag is required on Apple Silicon Macs because the CLI binary is compiled for x86_64. On Intel Macs and Linux, you can omit this flag.

Exec into the container:

bash

docker exec -it cpln-test bash

Test the CLI:

bash

# List all workloads
cpln workload get

Cleanup:

bash

docker stop cpln-test && docker rm cpln-test

Multi-stage builds keep the final image small by excluding download tools.

Pin the CLI version

Always pin the CLI version for reproducible builds:

ARG CPLN_CLI_VERSION=3.7.5
RUN npm install -g @controlplane/cli@${CPLN_CLI_VERSION}

ARG CPLN_BINARY_URL=https://storage.googleapis.com/artifacts.cpln-build.appspot.com/binaries/cpln/2650573345-9851fb16/cpln-linux.tgz

Check available versions:

npm: https://www.npmjs.com/package/@controlplane/cli
Binary: See Installation

Runtime authentication

Pass secrets via environment variables

Set at minimum CPLN_TOKEN when running the container:

docker run --rm \
  -e CPLN_TOKEN="$CPLN_TOKEN" \
  -e CPLN_ORG="my-org" \
  -e CPLN_GVC="my-gvc" \
  your-image:tag \
  cpln workload get

Never print CPLN_TOKEN in logs or commit it to version control.

Using cpln in automation

Once installed, execute CLI commands from your application code:

Node.js
Python
Go
Bash

import { spawn } from "node:child_process";

const proc = spawn("cpln", ["workload", "get", "--gvc", "my-gvc"], {
  stdio: "inherit",
  env: process.env,
});

proc.on("exit", (code) => {
  process.exit(code ?? 1);
});

import os
import subprocess
import sys

result = subprocess.run(
    ["cpln", "workload", "get", "--gvc", "my-gvc"],
    env=os.environ,
    check=False,
)

sys.exit(result.returncode)

package main

import (
    "os"
    "os/exec"
)

func main() {
    cmd := exec.Command("cpln", "workload", "get", "--gvc", "my-gvc")
    cmd.Env = os.Environ()
    cmd.Stdout = os.Stdout
    cmd.Stderr = os.Stderr

    if err := cmd.Run(); err != nil {
        os.Exit(1)
    }
}

#!/usr/bin/env bash
set -euo pipefail

# Ensure required environment variables are set
for var in CPLN_TOKEN CPLN_ORG CPLN_GVC; do
  if [ -z "${!var:-}" ]; then
    echo "Error: $var is not set"
    exit 1
  fi
done

# Create profile
cpln profile create ci --default

# Run commands
cpln workload get

Common workflows

Build and push images

cpln image build --name <image-name>:<image-tag> --push

Apply resources

# Apply from a file
cpln apply --file resources.yaml

# Apply from stdin
cat resources.yaml | cpln apply --file -

Execute workload commands

cpln workload get --gvc my-gvc
cpln workload exec my-app --gvc my-gvc -- echo hello world

Troubleshooting

cpln: not found

Verify the binary is in PATH and executable:

RUN cpln --version

Ensure the binary is copied to a directory in PATH (e.g., /usr/local/bin).

Authentication failures

Verify CPLN_TOKEN is set at runtime:

docker run --rm -e CPLN_TOKEN="$CPLN_TOKEN" your-image cpln profile get

Check the token isn’t truncated

Docker registry authentication issues

Re-run Docker login in your container:

cpln image docker-login

Ensure the service account has access to the image registry.

For more troubleshooting help, see the Troubleshooting page.

Best practices

Use multi-stage builds

Keep final images small by using multi-stage builds to separate download/build tools from the runtime image.

Pin the CLI version

Always specify an exact CLI version for reproducible builds:

ARG CPLN_CLI_VERSION=3.7.5
RUN npm install -g @controlplane/cli@${CPLN_CLI_VERSION}

ARG CPLN_BINARY_URL=https://storage.googleapis.com/artifacts.cpln-build.appspot.com/binaries/cpln/2650573345-9851fb16/cpln-linux.tgz
RUN curl -fsSL "${CPLN_BINARY_URL}" -o /tmp/cpln.tgz && \
    tar -xzf /tmp/cpln.tgz -C /usr/local/bin

Never bake credentials

Pass tokens at runtime via environment variables or secret managers. Never include them in the image.

Set CPLN_ORG and CPLN_GVC

Set CPLN_ORG and CPLN_GVC as environment variables so you don’t need to pass --org and --gvc flags with every command:

docker run --rm \
  -e CPLN_TOKEN="$CPLN_TOKEN" \
  -e CPLN_ORG="my-org" \
  -e CPLN_GVC="my-gvc" \
  your-image:tag

Verify installation in Dockerfile

Add a verification step:

RUN cpln --version

This catches installation issues during the build.

Next steps

CI/CD Usage

Complete CI/CD automation guide

Installation

CLI installation methods

Authentication

Authentication strategies

Profiles

Profile management

CLI Reference

Commands

Using the CLI in Containers

When to use this

Installation methods

Pin the CLI version

Runtime authentication

Pass secrets via environment variables

Using cpln in automation

Common workflows

Build and push images

Apply resources

Execute workload commands

Troubleshooting

Best practices

Next steps

CI/CD Usage

Installation

Authentication

Profiles

​When to use this

​Installation methods

​Pin the CLI version

​Runtime authentication

​Pass secrets via environment variables

​Using cpln in automation

​Common workflows

​Build and push images

​Apply resources

​Execute workload commands

​Troubleshooting

​Best practices

​Next steps

CI/CD Usage

Installation

Authentication

Profiles

When to use this

Installation methods

Pin the CLI version

Runtime authentication

Pass secrets via environment variables

Using cpln in automation

Common workflows

Build and push images

Apply resources

Execute workload commands

Troubleshooting

Best practices

Next steps