Copy Images Between Organizations

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

CLI installed

Install the Control Plane CLI. See Installation.

Docker installed

Install Docker. The CLI uses Docker to pull, tag, and push images.

Access to both organizations

You need:

Pull permission on images in the source org
Push permission on images in the destination org

See Image Permissions.

Profiles configured (for cross-org)

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:

Authenticates Docker to both organization registries
Pulls the image from your current org
Tags it for the destination org
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

Option	Description
`<ref>`	Source image reference (e.g., `my-app:v1`)
`--to-org`	Target organization to copy the image to
`--to-name`	New name and tag for the image (optional)
`--to-profile`	Profile for authenticating to the destination org (optional)
`--cleanup`	Remove 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

Authentication failed for source org

Verify you’re logged in to the source org:

cpln profile get

Re-authenticate if needed:

cpln login

Authentication failed for destination org

Check the destination profile has valid credentials:

cpln profile get dest-profile

Re-authenticate the profile:

cpln login dest-profile

Push denied

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.

Image not found

Verify the source image exists:

cpln image get my-app:v1

Check the exact image name and tag.

Docker daemon not running

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

How-to Guides

CLI Configuration

Integrations

Configure Resources

Create Resources

Deployment

GitOps

Images

Native Networking

Observability

Sandbox

Workload Access

Copy Images Between Organizations

When to use this

Cross-org sharing

Environment promotion

Image migration

Rename images

Prerequisites

Basic usage

Copy with a different name

Copy between orgs with different credentials

Clean up local images

Command reference

Common workflows

Environment promotion

CI/CD pipeline

Troubleshooting

Next steps

Push Images

Pull Images

Profiles

Image Reference

​When to use this

Cross-org sharing

Environment promotion

Image migration

Rename images

​Prerequisites

​Basic usage

​Copy with a different name

​Copy between orgs with different credentials

​Clean up local images

​Command reference

​Common workflows

​Environment promotion

​CI/CD pipeline

​Troubleshooting

​Next steps

Push Images

Pull Images

Profiles

Image Reference

When to use this

Prerequisites

Basic usage

Copy with a different name

Copy between orgs with different credentials

Clean up local images

Command reference

Common workflows

Environment promotion

CI/CD pipeline

Troubleshooting

Next steps