Images

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

Command	Description
`cpln image build`	Build and optionally push images
`cpln image docker-login`	Authenticate Docker to your org’s registry
`cpln image get`	List or view images in your org
`cpln image copy`	Copy images between organizations
`cpln image delete`	Delete 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:

Builds your image using the Dockerfile in the current directory
Tags it for your org’s private registry
Pushes it to your-org.registry.cpln.io/my-app:v1

Build Options

With Dockerfile
With Buildpacks

# 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

Flag	Description
`--dockerfile`	Path to Dockerfile (default: `./Dockerfile`)
`--dir`	Build context directory (default: current directory)
`--push`	Push the image to your org’s private registry after building
`--no-cache`	Build without using cache
`--platform`, `-p`	Target platform (default: `linux/amd64`)

When --dir is specified, the Dockerfile in that directory is used by default. Use --dockerfile to override this behavior.

cpln image build --name my-app:v1 --push

Buildpack options:

Flag	Description
`--builder`, `-B`	CNB-compatible builder image (default: `heroku/builder:24`)
`--buildpack`, `-b`	Additional buildpack to use (can be specified multiple times)
`--dir`	Build context directory (default: current directory)
`--push`	Push the image to your org’s private registry after building
`--no-cache`	Build without using cache
`--env`, `-e`	Environment variable for the build (can be specified multiple times)
`--env-file`	File containing environment variables (can be specified multiple times)
`--trust-builder`	Trust the builder image (skip security prompts)
`--trust-extra-buildpacks`	Trust additional buildpacks
`--platform`, `-p`	Target platform (default: `linux/amd64`)

Examples:

# Use a different builder
cpln image build --name my-app:v1 --push -B gcr.io/buildpacks/builder:google-22

# Add a specific buildpack (e.g., for Rust)
cpln image build --name my-rust-app:v1 --push -b docker.io/paketocommunity/rust

# Pass build-time environment variables
cpln image build --name my-app:v1 --push -e NODE_ENV=production -e LOG_LEVEL=info

# Use an env file
cpln image build --name my-app:v1 --push --env-file .env.build

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

# Trust builder and extra buildpacks (useful in CI/CD)
cpln image build --name my-app:v1 --push --trust-builder --trust-extra-buildpacks

Common builders:

Builder	Description
`heroku/builder:24`	Default. Supports Node.js, Python, Go, Java, Ruby, and more
`gcr.io/buildpacks/builder:google-22`	Google Cloud buildpacks
`paketobuildpacks/builder-jammy-base`	Paketo community buildpacks (includes .NET, Rust)

For language-specific requirements and conventions, see the Buildpacks Guide.

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

Format	Description
`//image/IMAGE:TAG`	Image in your org’s registry
`ORG.registry.cpln.io/IMAGE:TAG`	Image in another org’s registry
`nginx:latest`	Public image from Docker Hub
`gcr.io/project/IMAGE:TAG`	Image 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

unknown shorthand flag: 'f' in -f

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

Authentication failed or 403

Re-run cpln image docker-login to refresh credentials and double check that you don’t have typos in the org name.

Push denied

Verify you have push permission on images. Check your policies or refresh your service account token.

Image too large

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

CLI Reference

Commands

Quick Reference

Build and Push Images

Build Options

Use Images in Workloads

Image Reference Formats

Authenticate Docker

List and Manage Images

Copy Images Between Orgs

CI/CD Authentication

Troubleshooting

Learn More

Buildpacks Guide

Push Images

Pull Images

Image Command Reference

​Quick Reference

​Build and Push Images

​Build Options

​Use Images in Workloads

​Image Reference Formats

​Authenticate Docker

​List and Manage Images

​Copy Images Between Orgs

​CI/CD Authentication

​Troubleshooting

​Learn More

Buildpacks Guide

Push Images

Pull Images

Image Command Reference

Quick Reference

Build and Push Images

Build Options

Use Images in Workloads

Image Reference Formats

Authenticate Docker

List and Manage Images

Copy Images Between Orgs

CI/CD Authentication

Troubleshooting

Learn More