Skip to main content
Manage images and configure Docker login For a detailed overview, please visit the image’s reference page. 
cpln image [SUBCOMMAND]

Commands:
  cpln image access-report <ref>  Show the access report for the referenced image
  cpln image audit [ref]          Retrieve audit trail events for the referenced image
  cpln image build                Build and containerize an application into an image. If using buildpacks, everything after -- will be passed down to the pack executable.
  cpln image copy <ref>           Copy an image from one org to another. This will make sure that docker-login has been run against the source and destination org, then will pull, tag and push the image to the destination org.
  cpln image delete <ref...>      Delete one or more referenced images
  cpln image docker-login         Perform a Docker login to the organization's private registry
  cpln image edit <ref>           Edit the referenced image, as YAML, within an editor
  cpln image get [ref...]         Retrieve one or more referenced images
  cpln image patch <ref>          Update the referenced image's metadata using an input file
  cpln image permissions          Show the grantable permissions for an image object type
  cpln image query                Find all the images based on the given query
  cpln image tag <ref...>         Manage the tags belonging to one or more referenced images

Options:
  --help  Show help  [boolean]

​
image access-report

Show the access report for the referenced image Usage 
cpln image access-report <ref> [OPTIONS]

Positionals:
  ref  The resource reference. Usually it is the name of the resource.  [required]

Context options:
  --profile  Override the profile. The default profile can be set using the `cpln profile set-default` command or by setting the CPLN_PROFILE environment variable
  --org      Override the organization. The default organization can be set in your profile by using the `cpln profile update` command

Format options:
  --output, -o  Set the output format  [choices: "text", "json", "yaml", "json-slim", "yaml-slim", "tf", "crd", "names"]
  --color       Colorize the output  [boolean] [default: true]
  --ts          Timestamp format if the output format is text (e.g., --output=text)  [choices: "iso", "local", "age"]
  --max         Maximum number of records to show. A value less than 1 will return all records.  [number] [default: 50]

Request options:
  --token         Override the authorization token
  --endpoint      Override the API URL
  --insecure, -k  Ignore TLS errors  [boolean]

Debug options:
  --verbose, -v  Enable verbose output to stderr  [boolean] [default: false]
  --debug, -d    Show all HTTP communications  [boolean] [default: false]

Options:
  --help  Show help  [boolean]
Common Options Reference
cpln image access-report demo-image:1 --org demo-cpln-organization

​
image audit

Retrieve audit trail events for the referenced image Usage 
cpln image audit [ref] [OPTIONS]

Positionals:
  ref  The resource reference. Usually it is the name of the resource.

Command options:
  --subject  Filter by subject (serviceaccount name or user email)  [string]
  --context  Audit context name (the 'cpln' context displays Control Plane actions)  [string] [default: "cpln"]
  --since    Relative lookback window from now (e.g., 1h, 24h, 7d). Mutually exclusive with --from/--to  [string] [default: "7d"]
  --from     Start time for audit events (ISO 8601 format or relative duration, e.g., 2025-10-23T07:00:00Z, 7d, 1h). Cannot be used with --since  [string]
  --to       End time for audit events (ISO 8601 format or relative duration, e.g., 2025-10-23T07:00:00Z, 1d, 30m)  [string]

Context options:
  --profile  Override the profile. The default profile can be set using the `cpln profile set-default` command or by setting the CPLN_PROFILE environment variable
  --org      Override the organization. The default organization can be set in your profile by using the `cpln profile update` command

Format options:
  --output, -o  Set the output format  [choices: "text", "json", "yaml", "json-slim", "yaml-slim", "tf", "crd", "names"]
  --color       Colorize the output  [boolean] [default: true]
  --ts          Timestamp format if the output format is text (e.g., --output=text)  [choices: "iso", "local", "age"]
  --max         Maximum number of records to show. A value less than 1 will return all records.  [number] [default: 50]

Request options:
  --token         Override the authorization token
  --endpoint      Override the API URL
  --insecure, -k  Ignore TLS errors  [boolean]

Debug options:
  --verbose, -v  Enable verbose output to stderr  [boolean] [default: false]
  --debug, -d    Show all HTTP communications  [boolean] [default: false]

Options:
  --help  Show help  [boolean]
Common Options Reference

​
image build

Build and containerize an application into an image. If using buildpacks, everything after — will be passed down to the pack executable. Usage 
cpln image build --name IMAGE_NAME:TAG [OPTIONS]
To push an image using this command, the docker-credential-cpln executable must be installed if the CLI was not installed using npm.
The option --builder accepts any trusted buildpacks builder.The default buildpack is heroku/buildpacks:18.Docker is required to be installed.
Command options:
  --name, -n                Name and tag for the image  [required]
  --dockerfile              Path to Dockerfile (e.g.: PATH/Dockerfile). If set, the builder option is not used
  --builder, -B             Builder image to use (e.g., heroku/builder:24_linux-amd64, gcr.io/buildpacks/builder:google-22, paketobuildpacks/builder-jammy-full)  [default: "heroku/builder:24_linux-amd64"]
  --buildpack, -b           Buildpack to use. One of: buildpack ID and version (<buildpack>@<version>), path to a buildpack directory (not supported on Windows), path/URL to a .tar or .tgz file, or a packaged buildpack image (<hostname>/<repo>[:<tag>]). Repeat for each buildpack in order, or supply once by comma-separated list
  --env, -e                 Build-time environment variable in the form 'VAR=VALUE' or 'VAR' (value taken from current environment). Repeat for each env var. NOTE: These are NOT available at image runtime.
  --env-file                Build-time environment variables file. One variable per line, of the form 'VAR=VALUE' or 'VAR'. NOTE: These are NOT available at image runtime.
  --trust-builder           Trust the provided builder. All lifecycle phases will be run in a single container for better performance.  [boolean] [default: false]
  --trust-extra-buildpacks  Trust buildpacks that are provided in addition to the buildpacks on the builder  [boolean] [default: false]
  --dir                     Directory containing the application  [default: "."]
  --no-cache                Builds the image without using any cached layers.  [boolean] [default: false]
  --push                    Push the new image to the org's private registry  [boolean] [default: false]
  --platform, -p            Target platform(s) for the build (e.g., linux/amd64, linux/amd64,linux/arm64)  [default: "linux/amd64"]

Context options:
  --profile  Override the profile. The default profile can be set using the `cpln profile set-default` command or by setting the CPLN_PROFILE environment variable
  --org      Override the organization. The default organization can be set in your profile by using the `cpln profile update` command

Format options:
  --output, -o  Set the output format  [choices: "text", "json", "yaml", "json-slim", "yaml-slim", "tf", "crd", "names"]
  --color       Colorize the output  [boolean] [default: true]
  --ts          Timestamp format if the output format is text (e.g., --output=text)  [choices: "iso", "local", "age"]
  --max         Maximum number of records to show. A value less than 1 will return all records.  [number] [default: 50]

Request options:
  --token         Override the authorization token
  --endpoint      Override the API URL
  --insecure, -k  Ignore TLS errors  [boolean]

Debug options:
  --verbose, -v  Enable verbose output to stderr  [boolean] [default: false]
  --debug, -d    Show all HTTP communications  [boolean] [default: false]

Options:
  --help  Show help  [boolean]
Common Options Reference
cpln image build demo-image:1 --push demo-cpln-organization -- --env CPLN_IMAGE_BUILD=true

​
image copy

Copy an image from one org to another. This will make sure that docker-login has been run against the source and destination org, then will pull, tag and push the image to the destination org. Usage 
cpln image copy <ref> --to-name IMAGE:TAG --to-org TARGET_ORG --to-profile TARGET_ORG_PROFILE [OPTIONS]

Positionals:
  ref  The resource reference. Usually it is the name of the resource.  [required]

Command options:
  --to-name     Name and tag for the image
  --to-org      Target org to copy the image to
  --to-profile  Profile to use for accessing the "to-org" argument
  --cleanup     Cleans up the pulled and retagged image  [boolean] [default: false]

Context options:
  --profile  Override the profile. The default profile can be set using the `cpln profile set-default` command or by setting the CPLN_PROFILE environment variable
  --org      Override the organization. The default organization can be set in your profile by using the `cpln profile update` command
  --gvc      Override the global virtual cloud. The default global virtual cloud can be set in your profile by using the `cpln profile update` command

Format options:
  --output, -o  Set the output format  [choices: "text", "json", "yaml", "json-slim", "yaml-slim", "tf", "crd", "names"]
  --color       Colorize the output  [boolean] [default: true]
  --ts          Timestamp format if the output format is text (e.g., --output=text)  [choices: "iso", "local", "age"]
  --max         Maximum number of records to show. A value less than 1 will return all records.  [number] [default: 50]

Request options:
  --token         Override the authorization token
  --endpoint      Override the API URL
  --insecure, -k  Ignore TLS errors  [boolean]

Debug options:
  --verbose, -v  Enable verbose output to stderr  [boolean] [default: false]
  --debug, -d    Show all HTTP communications  [boolean] [default: false]

Options:
  --help  Show help  [boolean]
Common Options Reference
  • Copying image between orgs within the same profile
cpln image copy SOURCE_IMAGE:TAG --to-name TARGET_IMAGE:NEW_TAG --to-org TARGET_ORG
The profile service principal (user/service account) must have the proper permissions to pull/push images in the current and target org.
  • Copying image between orgs using different profiles
cpln image copy SOURCE_IMAGE:TAG --to-name TARGET_IMAGE:NEW_TAG --to-org TARGET_ORG --to-profile TARGET_ORG_PROFILE
This command will copy an image from the current org to the target org.The current profile service principal (user/service account) must have the proper permissions to pull images in the current org (default profile).The referenced —to-profile service principal (user/service account) must have the proper permissions to push images to the target org.This command allows the copying of images between different orgs using user or service account profiles.

​
image delete

Delete one or more referenced images Usage 
cpln image delete <ref...> [OPTIONS]

Positionals:
  ref  One or more resource references. Usually it is the name of the resource.  [array] [required] [default: []]

Context options:
  --profile  Override the profile. The default profile can be set using the `cpln profile set-default` command or by setting the CPLN_PROFILE environment variable
  --org      Override the organization. The default organization can be set in your profile by using the `cpln profile update` command

Format options:
  --output, -o  Set the output format  [choices: "text", "json", "yaml", "json-slim", "yaml-slim", "tf", "crd", "names"]
  --color       Colorize the output  [boolean] [default: true]
  --ts          Timestamp format if the output format is text (e.g., --output=text)  [choices: "iso", "local", "age"]
  --max         Maximum number of records to show. A value less than 1 will return all records.  [number] [default: 50]

Request options:
  --token         Override the authorization token
  --endpoint      Override the API URL
  --insecure, -k  Ignore TLS errors  [boolean]

Debug options:
  --verbose, -v  Enable verbose output to stderr  [boolean] [default: false]
  --debug, -d    Show all HTTP communications  [boolean] [default: false]

Options:
  --help  Show help  [boolean]
Common Options Reference
cpln image delete demo-image:1 --org demo-cpln-organization

​
image docker-login

Perform a Docker login to the organization’s private registry Usage 
cpln image docker-login [OPTIONS]

Command options:
  --ignore-output  Ignore the output of this command.

Context options:
  --profile  Override the profile. The default profile can be set using the `cpln profile set-default` command or by setting the CPLN_PROFILE environment variable
  --org      Override the organization. The default organization can be set in your profile by using the `cpln profile update` command

Format options:
  --output, -o  Set the output format  [choices: "text", "json", "yaml", "json-slim", "yaml-slim", "tf", "crd", "names"]
  --color       Colorize the output  [boolean] [default: true]
  --ts          Timestamp format if the output format is text (e.g., --output=text)  [choices: "iso", "local", "age"]
  --max         Maximum number of records to show. A value less than 1 will return all records.  [number] [default: 50]

Request options:
  --token         Override the authorization token
  --endpoint      Override the API URL
  --insecure, -k  Ignore TLS errors  [boolean]

Debug options:
  --verbose, -v  Enable verbose output to stderr  [boolean] [default: false]
  --debug, -d    Show all HTTP communications  [boolean] [default: false]

Options:
  --help  Show help  [boolean]
Common Options Reference
cpln image docker-login demo-image:1 --org demo-cpln-organization

​
image edit

Edit the referenced image, as YAML, within an editor Usage 
cpln image edit <ref> [OPTIONS]
The default editor can be set by using the EDITOR environment variable.
Positionals:
  ref  The resource reference. Usually it is the name of the resource.  [required]

Command options:
  --replace, -r  Replace instead of patch/merge  [boolean] [default: false]

Context options:
  --profile  Override the profile. The default profile can be set using the `cpln profile set-default` command or by setting the CPLN_PROFILE environment variable
  --org      Override the organization. The default organization can be set in your profile by using the `cpln profile update` command

Format options:
  --output, -o  Set the output format  [choices: "text", "json", "yaml", "json-slim", "yaml-slim", "tf", "crd", "names"]
  --color       Colorize the output  [boolean] [default: true]
  --ts          Timestamp format if the output format is text (e.g., --output=text)  [choices: "iso", "local", "age"]
  --max         Maximum number of records to show. A value less than 1 will return all records.  [number] [default: 50]

Request options:
  --token         Override the authorization token
  --endpoint      Override the API URL
  --insecure, -k  Ignore TLS errors  [boolean]

Debug options:
  --verbose, -v  Enable verbose output to stderr  [boolean] [default: false]
  --debug, -d    Show all HTTP communications  [boolean] [default: false]

Options:
  --help  Show help  [boolean]
Common Options Reference
cpln image edit demo-image:1 --org demo-cpln-organization

​
image get

Retrieve one or more referenced images Usage 
cpln image get [ref...] [OPTIONS]
An empty reference will return all references
Positionals:
  ref  One or more resource references. Usually it is the name of the resource.  [array] [default: []]

Context options:
  --profile  Override the profile. The default profile can be set using the `cpln profile set-default` command or by setting the CPLN_PROFILE environment variable
  --org      Override the organization. The default organization can be set in your profile by using the `cpln profile update` command

Format options:
  --output, -o  Set the output format  [choices: "text", "json", "yaml", "json-slim", "yaml-slim", "tf", "crd", "names"]
  --color       Colorize the output  [boolean] [default: true]
  --ts          Timestamp format if the output format is text (e.g., --output=text)  [choices: "iso", "local", "age"]
  --max         Maximum number of records to show. A value less than 1 will return all records.  [number] [default: 50]

Request options:
  --token         Override the authorization token
  --endpoint      Override the API URL
  --insecure, -k  Ignore TLS errors  [boolean]

Debug options:
  --verbose, -v  Enable verbose output to stderr  [boolean] [default: false]
  --debug, -d    Show all HTTP communications  [boolean] [default: false]

Options:
  --help  Show help  [boolean]
Common Options Reference
  • Get all images
cpln image get --org demo-cpln-organization
  • Get one image
cpln image get demo-image:1 --org demo-cpln-organization
  • Get multiple images
cpln image get demo-image:1 demo-image:2 --org demo-cpln-organization

​
image patch

Update the referenced image’s metadata using an input file Usage 
cpln image patch <ref> --file FILE_NAME [OPTIONS]
Running this command with the option --file - sets the input to stdin. The input is required to be a valid JSON or YAML string (e.g., {"description": "My new description"} or description: My new description). To complete the update, press Control-D (or Control-Z if you are using Windows).
Positionals:
  ref  The resource reference. Usually it is the name of the resource.  [required]

Command options:
  --file, -f  File to load the patch from. Use `--file -` to enable input from stdin.  [required]

Context options:
  --profile  Override the profile. The default profile can be set using the `cpln profile set-default` command or by setting the CPLN_PROFILE environment variable
  --org      Override the organization. The default organization can be set in your profile by using the `cpln profile update` command

Format options:
  --output, -o  Set the output format  [choices: "text", "json", "yaml", "json-slim", "yaml-slim", "tf", "crd", "names"]
  --color       Colorize the output  [boolean] [default: true]
  --ts          Timestamp format if the output format is text (e.g., --output=text)  [choices: "iso", "local", "age"]
  --max         Maximum number of records to show. A value less than 1 will return all records.  [number] [default: 50]

Request options:
  --token         Override the authorization token
  --endpoint      Override the API URL
  --insecure, -k  Ignore TLS errors  [boolean]

Debug options:
  --verbose, -v  Enable verbose output to stderr  [boolean] [default: false]
  --debug, -d    Show all HTTP communications  [boolean] [default: false]

Options:
  --help  Show help  [boolean]
Common Options Reference
cpln image patch demo-image:1 --file update.json --org demo-cpln-organization

​
image permissions

Show the grantable permissions for an image object type Usage 
cpln image permissions [OPTIONS]

Context options:
  --profile  Override the profile. The default profile can be set using the `cpln profile set-default` command or by setting the CPLN_PROFILE environment variable
  --org      Override the organization. The default organization can be set in your profile by using the `cpln profile update` command

Format options:
  --output, -o  Set the output format  [choices: "text", "json", "yaml", "json-slim", "yaml-slim", "tf", "crd", "names"]
  --color       Colorize the output  [boolean] [default: true]
  --ts          Timestamp format if the output format is text (e.g., --output=text)  [choices: "iso", "local", "age"]
  --max         Maximum number of records to show. A value less than 1 will return all records.  [number] [default: 50]

Request options:
  --token         Override the authorization token
  --endpoint      Override the API URL
  --insecure, -k  Ignore TLS errors  [boolean]

Debug options:
  --verbose, -v  Enable verbose output to stderr  [boolean] [default: false]
  --debug, -d    Show all HTTP communications  [boolean] [default: false]

Options:
  --help  Show help  [boolean]
Common Options Reference
cpln image permissions --org demo-cpln-organization

​
image query

Find all the images based on the given query Usage 
cpln image query QUERY_OPTIONS [OPTIONS]

Query options:
  --match             Query filter type  [choices: "all", "none", "any"] [default: "all"]
  --property, --prop  Property to query
  --tag               Tag to query
  --rel               Relation to query

Context options:
  --profile  Override the profile. The default profile can be set using the `cpln profile set-default` command or by setting the CPLN_PROFILE environment variable
  --org      Override the organization. The default organization can be set in your profile by using the `cpln profile update` command

Format options:
  --output, -o  Set the output format  [choices: "text", "json", "yaml", "json-slim", "yaml-slim", "tf", "crd", "names"]
  --color       Colorize the output  [boolean] [default: true]
  --ts          Timestamp format if the output format is text (e.g., --output=text)  [choices: "iso", "local", "age"]
  --max         Maximum number of records to show. A value less than 1 will return all records.  [number] [default: 50]

Request options:
  --token         Override the authorization token
  --endpoint      Override the API URL
  --insecure, -k  Ignore TLS errors  [boolean]

Debug options:
  --verbose, -v  Enable verbose output to stderr  [boolean] [default: false]
  --debug, -d    Show all HTTP communications  [boolean] [default: false]

Options:
  --help  Show help  [boolean]
Common Options Reference
Use the --match option to display all, none, or any of the results based on a given property or tag
  • Search for an image based on the name property
cpln image query --match any --prop name=demo-image:1 --org demo-cpln-organization
  • Search for an image based on the description property
cpln image query --match any --prop tag="2" --org demo-cpln-organization
  • Search for an image based on a tag
cpln image query --match any --tag description="Demo Image #1" --org demo-cpln-organization
  • Search for an image based on a property and tag
cpln image query --match any --prop name="demo-image" --tag description="Demo Image #1" --org demo-cpln-organization

​
image tag

Manage the tags belonging to one or more referenced images Usage 
cpln image tag <ref...> --tag KEY=VALUE [OPTIONS]
Built-in tags, which begin with cpln/*, can’t be modified.
Positionals:
  ref  One or more resource references. Usually it is the name of the resource.  [array] [required] [default: []]

Command options:
  --tag         Attach tags (e.g., --tag drink=water)
  --remove-tag  Remove tags (e.g., --remove-tag tagname)

Context options:
  --profile  Override the profile. The default profile can be set using the `cpln profile set-default` command or by setting the CPLN_PROFILE environment variable
  --org      Override the organization. The default organization can be set in your profile by using the `cpln profile update` command

Format options:
  --output, -o  Set the output format  [choices: "text", "json", "yaml", "json-slim", "yaml-slim", "tf", "crd", "names"]
  --color       Colorize the output  [boolean] [default: true]
  --ts          Timestamp format if the output format is text (e.g., --output=text)  [choices: "iso", "local", "age"]
  --max         Maximum number of records to show. A value less than 1 will return all records.  [number] [default: 50]

Request options:
  --token         Override the authorization token
  --endpoint      Override the API URL
  --insecure, -k  Ignore TLS errors  [boolean]

Debug options:
  --verbose, -v  Enable verbose output to stderr  [boolean] [default: false]
  --debug, -d    Show all HTTP communications  [boolean] [default: false]

Options:
  --help  Show help  [boolean]
Common Options Reference
  • Add a tag
cpln image tag demo-image:1 --tag drink=water --org demo-cpln-organization
  • Update same tag (after running the example above)
cpln image tag demo-image:1 --tag drink=coffee --org demo-cpln-organization
  • Remove tag (after running the example above)
cpln image tag demo-image:1 --remove drink --org demo-cpln-organization