> ## Documentation Index
> Fetch the complete documentation index at: https://docs.controlplane.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Copy Images Between Organizations

> Copy container images from one Control Plane organization to another using the CLI.

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

<CardGroup cols={2}>
  <Card title="Cross-org sharing" icon="share-nodes">
    Share images between teams in different organizations
  </Card>

  <Card title="Environment promotion" icon="arrow-right-arrow-left">
    Promote images from dev to staging to production orgs
  </Card>

  <Card title="Image migration" icon="truck-moving">
    Migrate images when reorganizing or splitting organizations
  </Card>

  <Card title="Rename images" icon="tag">
    Copy images with new names or tags
  </Card>
</CardGroup>

## Prerequisites

<AccordionGroup>
  <Accordion title="CLI installed">
    Install the Control Plane CLI. See [Installation](/cli-reference/installation).
  </Accordion>

  <Accordion title="Docker installed">
    Install [Docker](https://www.docker.com). The CLI uses Docker to pull, tag, and push images.
  </Accordion>

  <Accordion title="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](/reference/image#minimum-policy).
  </Accordion>

  <Accordion title="Profiles configured (for cross-org)">
    If copying between orgs that use different credentials, create a profile for each org:

    ```bash theme={null}
    # 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](/cli-reference/get-started/profiles) for details.
  </Accordion>
</AccordionGroup>

## Basic usage

Copy an image to another organization:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
cpln image copy my-app:v1 \
  --to-org destination-org \
  --to-profile dest-profile
```

<Tip>
  Your default profile (or `CPLN_PROFILE`) is used for the source org. The `--to-profile` flag specifies credentials for the destination.
</Tip>

## 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:

```bash theme={null}
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:

```bash theme={null}
# 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:

```bash theme={null}
# 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

<AccordionGroup>
  <Accordion title="Authentication failed for source org">
    Verify you're logged in to the source org:

    ```bash theme={null}
    cpln profile get
    ```

    Re-authenticate if needed:

    ```bash theme={null}
    cpln login
    ```
  </Accordion>

  <Accordion title="Authentication failed for destination org">
    Check the destination profile has valid credentials:

    ```bash theme={null}
    cpln profile get dest-profile
    ```

    Re-authenticate the profile:

    ```bash theme={null}
    cpln login dest-profile
    ```
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="Image not found">
    Verify the source image exists:

    ```bash theme={null}
    cpln image get my-app:v1
    ```

    Check the exact image name and tag.
  </Accordion>

  <Accordion title="Docker daemon not running">
    Start Docker Desktop or the Docker daemon.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Push Images" href="/guides/push-image" icon="upload">
    Build and push new images to your registry
  </Card>

  <Card title="Pull Images" href="/guides/pull-image" icon="download">
    Configure workloads to pull images
  </Card>

  <Card title="Profiles" href="/cli-reference/get-started/profiles" icon="user">
    Manage multiple org contexts
  </Card>

  <Card title="Image Reference" href="/reference/image" icon="book">
    Image configuration details
  </Card>
</CardGroup>