Skip to main content
Copy container images between Control Plane organizations. The CLI handles authentication to both registries automatically, pulling, retagging, and pushing the image in one command.

​
When to use this

Cross-org sharing

Share images between teams in different organizations

Environment promotion

Promote images from dev to staging to production orgs

Image migration

Migrate images when reorganizing or splitting organizations

Rename images

Copy images with new names or tags

​
Prerequisites

Install the Control Plane CLI. See Installation.
Install Docker. The CLI uses Docker to pull, tag, and push images.
You need:
  • Pull permission on images in the source org
  • Push permission on images in the destination org
See Image Permissions.
If copying between orgs that use different credentials, create a profile for each org:
# Profile for source org and mark it as default
cpln profile create source-profile --login --org source-org --default

# Profile for destination org
cpln profile create dest-profile --login --org dest-org
See Profiles for details.

​
Basic usage

Copy an image to another organization: 
cpln image copy my-app:v1 --to-org destination-org
This command:
  1. Authenticates Docker to both organization registries
  2. Pulls the image from your current org
  3. Tags it for the destination org
  4. Pushes it to the destination org

​
Copy with a different name

Use --to-name to rename the image during copy: 
cpln image copy my-app:v1 --to-org destination-org --to-name renamed-app:v1
This copies my-app:v1 to destination-org as renamed-app:v1.

​
Copy between orgs with different credentials

When organizations use different authentication contexts, specify a profile for the destination org: 
cpln image copy my-app:v1 \
  --to-org destination-org \
  --to-profile dest-profile
Your default profile (or CPLN_PROFILE) is used for the source org. The --to-profile flag specifies credentials for the destination.

​
Clean up local images

By default, the CLI leaves the pulled and retagged images on your local machine. Use --cleanup to remove them after a successful copy: 
cpln image copy my-app:v1 --to-org destination-org --cleanup
This is useful in CI/CD pipelines to avoid filling up disk space.

​
Command reference

OptionDescription
<ref>Source image reference (e.g., my-app:v1)
--to-orgTarget organization to copy the image to
--to-nameNew name and tag for the image (optional)
--to-profileProfile for authenticating to the destination org (optional)
--cleanupRemove local images after successful copy (default: false)

​
Common workflows

​
Environment promotion

Promote an image from development to production: 
# Using default profile for dev org
cpln image copy my-app:v1.2.3 \
  --to-org my-org-production \
  --to-profile production-profile

​
CI/CD pipeline

Copy and clean up in automated pipelines: 
# Copy with cleanup to save disk space
cpln image copy my-app:$CI_COMMIT_SHA \
  --to-org production-org \
  --to-profile prod-profile \
  --cleanup

​
Troubleshooting

Verify you’re logged in to the source org:
cpln profile get
Re-authenticate if needed:
cpln login
Check the destination profile has valid credentials:
cpln profile get dest-profile
Re-authenticate the profile:
cpln login dest-profile
Verify you have push permission on images in the destination org. Check your policies or ask an org admin to grant access. Also check the org name for any typos.
Verify the source image exists:
cpln image get my-app:v1
Check the exact image name and tag.
Start Docker Desktop or the Docker daemon.

​
Next steps

Push Images

Build and push new images to your registry

Pull Images

Configure workloads to pull images

Profiles

Manage multiple org contexts

Image Reference

Image configuration details