Skip to main content
The CLI provides powerful commands for working with container images. Build locally, push to your org’s private registry, pull from external registries, and copy images between organizations.

​
Quick Reference

CommandDescription
cpln image buildBuild and optionally push images
cpln image docker-loginAuthenticate Docker to your org’s registry
cpln image getList or view images in your org
cpln image copyCopy images between organizations
cpln image deleteDelete images from your registry

​
Build and Push Images

The most common workflow is building and pushing a local application: 
cpln image build --name my-app:v1 --push
This command:
  1. Builds your image using the Dockerfile in the current directory
  2. Tags it for your org’s private registry
  3. Pushes it to your-org.registry.cpln.io/my-app:v1

​
Build Options

# Build from current directory
cpln image build --name my-app:v1 --push

# Specify a Dockerfile
cpln image build --name my-app:v1 --dockerfile ./docker/Dockerfile.prod --push

# Build from a different directory
cpln image build --name my-app:v1 --push --dir ./my-project

# Build for a different platform
cpln image build --name my-app:v1 --push --platform linux/arm64

# Build without cache
cpln image build --name my-app:v1 --push --no-cache
FlagDescription
--dockerfilePath to Dockerfile (default: ./Dockerfile)
--dirBuild context directory (default: current directory)
--pushPush the image to your org’s private registry after building
--no-cacheBuild without using cache
--platform, -pTarget platform (default: linux/amd64)
When --dir is specified, the Dockerfile in that directory is used by default. Use --dockerfile to override this behavior.

​
Use Images in Workloads

Reference your pushed images when creating workloads: 
cpln workload create --name my-app --gvc my-gvc \
  --image //image/my-app:v1 --port 8080 --public

​
Image Reference Formats

FormatDescription
//image/IMAGE:TAGImage in your org’s registry
ORG.registry.cpln.io/IMAGE:TAGImage in another org’s registry
nginx:latestPublic image from Docker Hub
gcr.io/project/IMAGE:TAGImage from Google Container Registry

​
Authenticate Docker

For direct Docker operations, authenticate to your org’s registry: 
cpln image docker-login
Then use standard Docker commands: 
docker pull your-org.registry.cpln.io/my-app:v1
docker push your-org.registry.cpln.io/my-app:v1

​
List and Manage Images

# List all images in your org
cpln image get

# Get details for a specific image
cpln image get my-app:v1

# Delete an image
cpln image delete my-app:v1

​
Copy Images Between Orgs

Copy an image to another organization: 
cpln image copy my-app:v1 --to-org destination-org
Copy with a different name: 
cpln image copy my-app:v1 --to-org destination-org --to-name renamed-app:v1
For cross-org copies with different credentials, use --to-profile. See the Copy Images guide.

​
CI/CD Authentication

For automated pipelines, set CPLN_TOKEN in your CI/CD platform’s secrets (e.g., GitLab CI/CD variables, GitHub secrets) and use the CLI directly: 
cpln image build --name my-app:$CI_COMMIT_SHA --push
The CLI automatically uses CPLN_TOKEN when available. For direct Docker access, authenticate with a service account: 
echo $CPLN_TOKEN | docker login your-org.registry.cpln.io -u '<token>' --password-stdin
See CI/CD Usage for complete automation setup.

​
Troubleshooting

Docker Buildx is not installed. Install it:
curl -sSL "https://github.com/docker/buildx/releases/download/v0.29.1/buildx-v0.29.1.linux-amd64" \
  | install -m 0755 -D /dev/stdin ~/.docker/cli-plugins/docker-buildx
Re-run cpln image docker-login to refresh credentials and double check that you don’t have typos in the org name.
Verify you have push permission on images. Check your policies or refresh your service account token.
Optimize your Dockerfile:
  • Use multi-stage builds
  • Start from smaller base images
  • Remove unnecessary files

​
Learn More

Buildpacks Guide

Language-specific conventions for building without Dockerfiles

Push Images

Detailed guide for building and pushing images

Pull Images

Configure workloads to pull from private registries

Image Command Reference

Full command documentation