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

# Images

> Build, push, pull, and manage container images with the Control Plane CLI.

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:

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

<Tabs>
  <Tab title="With Dockerfile">
    ```bash theme={null}
    # 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`)                     |

    <Info>
      When `--dir` is specified, the Dockerfile in that directory is used by default. Use `--dockerfile` to override this behavior.
    </Info>
  </Tab>

  <Tab title="With Buildpacks">
    ```bash theme={null}
    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:**

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

    <Info>
      For language-specific requirements and conventions, see the [Buildpacks Guide](/guides/buildpacks).
    </Info>
  </Tab>
</Tabs>

## Use Images in Workloads

Reference your pushed images when creating workloads:

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

```bash theme={null}
cpln image docker-login
```

Then use standard Docker commands:

```bash theme={null}
docker pull your-org.registry.cpln.io/my-app:v1
docker push your-org.registry.cpln.io/my-app:v1
```

## List and Manage Images

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

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

Copy with a different name:

```bash theme={null}
cpln image copy my-app:v1 --to-org destination-org --to-name renamed-app:v1
```

<Info>
  For cross-org copies with different credentials, use `--to-profile`. See the [Copy Images guide](/guides/copy-image).
</Info>

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

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

```bash theme={null}
echo $CPLN_TOKEN | docker login your-org.registry.cpln.io -u '<token>' --password-stdin
```

See [CI/CD Usage](/cli-reference/ci-cd-development/ci-cd) for complete automation setup.

## Troubleshooting

<AccordionGroup>
  <Accordion title="unknown shorthand flag: 'f' in -f">
    Docker Buildx is not installed. Install it:

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

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

  <Accordion title="Push denied">
    Verify you have push permission on images. Check your policies or refresh your service account token.
  </Accordion>

  <Accordion title="Image too large">
    Optimize your Dockerfile:

    * Use multi-stage builds
    * Start from smaller base images
    * Remove unnecessary files
  </Accordion>
</AccordionGroup>

## Learn More

<CardGroup cols={2}>
  <Card title="Buildpacks Guide" href="/guides/buildpacks" icon="cubes">
    Language-specific conventions for building without Dockerfiles
  </Card>

  <Card title="Push Images" href="/guides/push-image" icon="upload">
    Detailed guide for building and pushing images
  </Card>

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

  <Card title="Image Command Reference" href="/cli-reference/commands/image" icon="book">
    Full command documentation
  </Card>
</CardGroup>