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

# image

> cpln image — Build, push and manage container images to Control Plane and configure Docker registry authentication.

Manage images and configure Docker login

For a detailed overview, please visit the [image's](/reference/image) reference page.

```none theme={null}
cpln image [SUBCOMMAND]
```

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

```none theme={null}
cpln image access-report <ref> [OPTIONS]
```

<Accordion title="Reference">
  ```text theme={null}
  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](/cli-reference/using-cli/common-options)
</Accordion>

<Accordion title="Example">
  <CodeGroup>
    ```bash Command theme={null}
    cpln image access-report demo-image:1 --org demo-cpln-organization
    ```

    ```text Output theme={null}
    +-----------+--------------------------------------------------------+--------+
    |PERMISSION |PRINCIPAL                                               |GRANTED |
    |-----------|--------------------------------------------------------|--------|
    |create     |/org/demo-cpln-organization/group/superusers            |manage  |
    |create     |/org/demo-cpln-organization/serviceaccount/controlplane |manage  |
    |delete     |/org/demo-cpln-organization/group/superusers            |manage  |
    |delete     |/org/demo-cpln-organization/serviceaccount/controlplane |manage  |
    |edit       |/org/demo-cpln-organization/group/superusers            |manage  |
    |edit       |/org/demo-cpln-organization/serviceaccount/controlplane |manage  |
    |manage     |/org/demo-cpln-organization/group/superusers            |manage  |
    |manage     |/org/demo-cpln-organization/serviceaccount/controlplane |manage  |
    |pull       |/org/demo-cpln-organization/group/superusers            |manage  |
    |pull       |/org/demo-cpln-organization/serviceaccount/controlplane |manage  |
    |view       |/org/demo-cpln-organization/group/viewers               |view    |
    |view       |/org/demo-cpln-organization/group/superusers            |manage  |
    |view       |/org/demo-cpln-organization/serviceaccount/controlplane |manage  |
    +-----------+--------------------------------------------------------+--------+
    ```
  </CodeGroup>
</Accordion>

***

#### image audit

Retrieve audit trail events for the referenced image

**Usage**

```none theme={null}
cpln image audit [ref] [OPTIONS]
```

<Accordion title="Reference">
  ```text theme={null}
  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](/cli-reference/using-cli/common-options)
</Accordion>

***

#### image build

Build and containerize an application into an image. If using buildpacks, everything after -- will be passed down to the pack executable.

**Usage**

```none theme={null}
cpln image build --name IMAGE_NAME:TAG [OPTIONS]
```

<Warning>
  To push an image using this command, the [docker-credential-cpln](/cli-reference/installation#binary) executable must be installed if the CLI was not installed using npm.
</Warning>

<Info>
  The option `--builder` accepts any trusted [buildpacks](https://buildpacks.io/docs/) builder.

  The default buildpack is `heroku/buildpacks:18`.

  [Docker](https://www.docker.com/) is required to be installed.
</Info>

<Accordion title="Reference">
  ```text theme={null}
  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](/cli-reference/using-cli/common-options)
</Accordion>

<Accordion title="Example">
  <CodeGroup>
    ```bash Command theme={null}
    cpln image build demo-image:1 --push demo-cpln-organization -- --env CPLN_IMAGE_BUILD=true
    ```

    ```text Output theme={null}
    If the build was successful, the newly generated container image will be pushed to the referenced org's private registry.


    If using buildpacks, every flag after the -- is passed to the pack binary.

    Below are the available flags from the pack build command.


    Pack Build uses Cloud Native Buildpacks to create a runnable app image from source code.

    Pack Build requires an image name, which will be generated from the source code. Build defaults to the current directory, but you can use \`--path\` to specify another source code directory. Build requires a \`builder\`, which can either be provided directly to build using \`--builder\`, or can be set using the \`set-default-builder\` command. For more on how to use \`pack build\`, see: https://buildpacks.io/docs/app-developer-guide/build-an-app/.

    Usage:
      pack build <image-name> [flags]

    Examples:
    pack build test_img --path apps/test-app --builder cnbs/sample-builder:bionic

    Flags:
      -B, --builder string              Builder image
      -b, --buildpack strings           Buildpack to use. One of:
                                          a buildpack by id and version in the form of '<buildpack>@<version>',
                                          path to a buildpack directory (not supported on Windows),
                                          path/URL to a buildpack .tar or .tgz file, or
                                          a packaged buildpack image name in the form of '<hostname>/<repo>[:<tag>]'
                                        Repeat for each buildpack in order, or supply once by comma-separated list
      -r, --buildpack-registry string   Buildpack Registry by name
          --cache-image string          Cache build layers in remote registry. Requires --publish
          --clear-cache                 Clear image's associated cache before building
      -D, --default-process string      Set the default process type. (default "web")
      -d, --descriptor string           Path to the project descriptor file
          --docker-host string          Address to docker daemon that will be exposed to the build container.
                                        If not set (or set to empty string) the standard socket location will be used.
                                        Special value 'inherit' may be used in which case DOCKER_HOST environment variable will be used.
                                        This option may set DOCKER_HOST environment variable for the build container if needed.

      -e, --env stringArray             Build-time environment variable, in the form 'VAR=VALUE' or 'VAR'.
                                        When using latter value-less form, value will be taken from current
                                          environment at the time this command is executed.
                                        This flag may be specified multiple times and will override
                                          individual values defined by --env-file.
                                        Repeat for each env in order (comma-separated lists not accepted)
                                        NOTE: These are NOT available at image runtime.
          --env-file stringArray        Build-time environment variables file
                                        One variable per line, of the form 'VAR=VALUE' or 'VAR'
                                        When using latter value-less form, value will be taken from current
                                          environment at the time this command is executed
                                        NOTE: These are NOT available at image runtime."
          --gid int                     Override GID of user's group in the stack's build and run images. The provided value must be a positive number
      -h, --help                        Help for 'build'
          --lifecycle-image string      Custom lifecycle image to use for analysis, restore, and export when builder is untrusted.
          --network string              Connect detect and build containers to network
      -p, --path string                 Path to app dir or zip-formatted file (defaults to current working directory)
          --previous-image string       Set previous image to a particular tag reference, digest reference, or (when performing a daemon build) image ID
          --publish                     Publish to registry
          --pull-policy string          Pull policy to use. Accepted values are always, never, and if-not-present. (default "always")
          --run-image string            Run image (defaults to default stack's run image)
      -t, --tag strings                 Additional tags to push the output image to.
                                        Tags should be in the format 'image:tag' or 'repository/image:tag'.
                                        Repeat for each tag in order, or supply once by comma-separated list
          --trust-builder               Trust the provided builder
                                        All lifecycle phases will be run in a single container (if supported by the lifecycle).
          --volume stringArray          Mount host volume into the build container, in the form '<host path>:<target path>[:<options>]'.
                                        - 'host path': Name of the volume or absolute directory path to mount.
                                        - 'target path': The path where the file or directory is available in the container.
                                        - 'options' (default "ro"): An optional comma separated list of mount options.
                                            - "ro", volume contents are read-only.
                                            - "rw", volume contents are readable and writeable.
                                            - "volume-opt=<key>=<value>", can be specified more than once, takes a key-value pair consisting of the option name and its value.
                                        Repeat for each volume in order (comma-separated lists not accepted)
          --workspace string            Location at which to mount the app dir in the build image

    Global Flags:
          --no-color     Disable color output
      -q, --quiet        Show less output
          --timestamps   Enable timestamps in output
      -v, --verbose      Show more output
    ```
  </CodeGroup>
</Accordion>

***

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

```none theme={null}
cpln image copy <ref> --to-name IMAGE:TAG --to-org TARGET_ORG --to-profile TARGET_ORG_PROFILE [OPTIONS]
```

<Accordion title="Reference">
  ```text theme={null}
  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](/cli-reference/using-cli/common-options)
</Accordion>

<Accordion title="Example">
  * Copying image between orgs within the same profile

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

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

***

#### image delete

Delete one or more referenced images

**Usage**

```none theme={null}
cpln image delete <ref...> [OPTIONS]
```

<Accordion title="Reference">
  ```text theme={null}
  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](/cli-reference/using-cli/common-options)
</Accordion>

<Accordion title="Example">
  <CodeGroup>
    ```bash Command theme={null}
    cpln image delete demo-image:1 --org demo-cpln-organization
    ```

    ```text Output theme={null}
    If the delete was successful, a new command prompt will be shown.
    ```
  </CodeGroup>
</Accordion>

***

#### image docker-login

Perform a Docker login to the organization's private registry

**Usage**

```none theme={null}
cpln image docker-login [OPTIONS]
```

<Accordion title="Reference">
  ```text theme={null}
  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](/cli-reference/using-cli/common-options)
</Accordion>

<Accordion title="Example">
  <CodeGroup>
    ```bash Command theme={null}
    cpln image docker-login demo-image:1 --org demo-cpln-organization
    ```

    ```text Output theme={null}
    If the login was successful, the local Docker instance will have the abiltity to login to the referenced organization's private registry.
    ```
  </CodeGroup>
</Accordion>

***

#### image edit

Edit the referenced image, as YAML, within an editor

**Usage**

```none theme={null}
cpln image edit <ref> [OPTIONS]
```

<Note>
  The default editor can be set by using the EDITOR environment variable.
</Note>

<Accordion title="Reference">
  ```text theme={null}
  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](/cli-reference/using-cli/common-options)
</Accordion>

<Accordion title="Example">
  <CodeGroup>
    ```bash Command theme={null}
    cpln image edit demo-image:1 --org demo-cpln-organization
    ```

    ```text Output theme={null}
    Your default editor will be launched.

    Once any modifications are saved, the updates will be sent to the API.
    ```
  </CodeGroup>
</Accordion>

***

#### image get

Retrieve one or more referenced images

**Usage**

```none theme={null}
cpln image get [ref...] [OPTIONS]
```

<Note>
  An empty reference will return all references
</Note>

<Accordion title="Reference">
  ```text theme={null}
  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](/cli-reference/using-cli/common-options)
</Accordion>

<Accordion title="Example">
  * Get all images

  <CodeGroup>
    ```bash Command theme={null}
    cpln image get --org demo-cpln-organization
    ```

    ```text Output theme={null}
    +-------------+----------------------------------------------------------+-----------------+------------+----------------------------+
    |NAME         |PULL                                                      |DIGEST           |CREATED     |TAGS                        |
    |-------------|----------------------------------------------------------|-----------------|------------|----------------------------|
    |demo-image:1 |demo-cpln-organization.registry.test.cpln.io/demo-image:1 |sha256:3fe719... |2 years ago |                            |
    |demo-image:2 |demo-cpln-organization.registry.test.cpln.io/demo-image:2 |sha256:3fe719... |5 years ago |description="Demo Image #1" |
    +-------------+----------------------------------------------------------+-----------------+------------+----------------------------+
    ```
  </CodeGroup>

  * Get one image

  <CodeGroup>
    ```bash Command theme={null}
    cpln image get demo-image:1 --org demo-cpln-organization
    ```

    ```text Output theme={null}
    +-------------+----------------------------------------------------------+-----------------+------------+-----+
    |NAME         |PULL                                                      |DIGEST           |CREATED     |TAGS |
    |-------------|----------------------------------------------------------|-----------------|------------|-----|
    |demo-image:1 |demo-cpln-organization.registry.test.cpln.io/demo-image:1 |sha256:3fe719... |2 years ago |     |
    +-------------+----------------------------------------------------------+-----------------+------------+-----+
    ```
  </CodeGroup>

  * Get multiple images

  <CodeGroup>
    ```bash Command theme={null}
    cpln image get demo-image:1 demo-image:2 --org demo-cpln-organization
    ```

    ```text Output theme={null}
    +-------------+----------------------------------------------------------+-----------------+------------+----------------------------+
    |NAME         |PULL                                                      |DIGEST           |CREATED     |TAGS                        |
    |-------------|----------------------------------------------------------|-----------------|------------|----------------------------|
    |demo-image:1 |demo-cpln-organization.registry.test.cpln.io/demo-image:1 |sha256:3fe719... |2 years ago |                            |
    |demo-image:2 |demo-cpln-organization.registry.test.cpln.io/demo-image:2 |sha256:3fe719... |5 years ago |description="Demo Image #1" |
    +-------------+----------------------------------------------------------+-----------------+------------+----------------------------+
    ```
  </CodeGroup>
</Accordion>

***

#### image patch

Update the referenced image's metadata using an input file

**Usage**

```none theme={null}
cpln image patch <ref> --file FILE_NAME [OPTIONS]
```

<Note>
  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).
</Note>

<Accordion title="Reference">
  ```text theme={null}
  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](/cli-reference/using-cli/common-options)
</Accordion>

<Accordion title="Example">
  <CodeGroup>
    ```bash Command theme={null}
    cpln image patch demo-image:1 --file update.json --org demo-cpln-organization
    ```

    ```text Output theme={null}
    The changes within the JSON file will be performed against the referenced image.
    ```
  </CodeGroup>
</Accordion>

***

#### image permissions

Show the grantable permissions for an image object type

**Usage**

```none theme={null}
cpln image permissions [OPTIONS]
```

<Accordion title="Reference">
  ```text theme={null}
  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](/cli-reference/using-cli/common-options)
</Accordion>

<Accordion title="Example">
  <CodeGroup>
    ```bash Command theme={null}
    cpln image permissions --org demo-cpln-organization
    ```

    ```text Output theme={null}
    +-------+-----------------------------------------+-----------------------------------------+
    |NAME   |DESCRIPTION                              |IMPLIES                                  |
    |-------|-----------------------------------------|-----------------------------------------|
    |create |Create new image. You can push if you... |pull                                     |
    |delete |Delete                                   |                                         |
    |edit   |Modify existing image (only tags can ... |view                                     |
    |manage |Full access                              |create, delete, edit, manage, pull, view |
    |pull   |Image can be pulled                      |view                                     |
    |view   |Read-only access                         |                                         |
    +-------+-----------------------------------------+-----------------------------------------+
    ```
  </CodeGroup>
</Accordion>

***

#### image query

Find all the images based on the given query

**Usage**

```none theme={null}
cpln image query QUERY_OPTIONS [OPTIONS]
```

<Accordion title="Reference">
  ```text theme={null}
  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](/cli-reference/using-cli/common-options)
</Accordion>

<Accordion title="Example">
  <Note>
    Use the `--match` option to display **all**, **none**, or **any** of the results based on a given property or tag
  </Note>

  * Search for an image based on the name property

  <CodeGroup>
    ```bash Command theme={null}
    cpln image query --match any --prop name=demo-image:1 --org demo-cpln-organization
    ```

    ```text Output theme={null}
    +-------------+----------------------------------------------------------+-----------------+------------+-----+
    |NAME         |PULL                                                      |DIGEST           |CREATED     |TAGS |
    |-------------|----------------------------------------------------------|-----------------|------------|-----|
    |demo-image:1 |demo-cpln-organization.registry.test.cpln.io/demo-image:1 |sha256:3fe719... |2 years ago |     |
    +-------------+----------------------------------------------------------+-----------------+------------+-----+
    ```
  </CodeGroup>

  * Search for an image based on the description property

  <CodeGroup>
    ```bash Command theme={null}
    cpln image query --match any --prop tag="2" --org demo-cpln-organization
    ```

    ```text Output theme={null}
    +-------------+----------------------------------------------------------+-----------------+------------+----------------------------+
    |NAME         |PULL                                                      |DIGEST           |CREATED     |TAGS                        |
    |-------------|----------------------------------------------------------|-----------------|------------|----------------------------|
    |demo-image:2 |demo-cpln-organization.registry.test.cpln.io/demo-image:2 |sha256:3fe719... |5 years ago |description="Demo Image #1" |
    +-------------+----------------------------------------------------------+-----------------+------------+----------------------------+
    ```
  </CodeGroup>

  * Search for an image based on a tag

  <CodeGroup>
    ```bash Command theme={null}
    cpln image query --match any --tag description="Demo Image #1" --org demo-cpln-organization
    ```

    ```text Output theme={null}
    +-------------+----------------------------------------------------------+-----------------+------------+----------------------------+
    |NAME         |PULL                                                      |DIGEST           |CREATED     |TAGS                        |
    |-------------|----------------------------------------------------------|-----------------|------------|----------------------------|
    |demo-image:2 |demo-cpln-organization.registry.test.cpln.io/demo-image:2 |sha256:3fe719... |5 years ago |description="Demo Image #1" |
    +-------------+----------------------------------------------------------+-----------------+------------+----------------------------+
    ```
  </CodeGroup>

  * Search for an image based on a property and tag

  <CodeGroup>
    ```bash Command theme={null}
    cpln image query --match any --prop name="demo-image" --tag description="Demo Image #1" --org demo-cpln-organization
    ```

    ```text Output theme={null}
    +-------------+----------------------------------------------------------+-----------------+------------+----------------------------+
    |NAME         |PULL                                                      |DIGEST           |CREATED     |TAGS                        |
    |-------------|----------------------------------------------------------|-----------------|------------|----------------------------|
    |demo-image:2 |demo-cpln-organization.registry.test.cpln.io/demo-image:2 |sha256:3fe719... |5 years ago |description="Demo Image #1" |
    +-------------+----------------------------------------------------------+-----------------+------------+----------------------------+
    ```
  </CodeGroup>
</Accordion>

***

#### image tag

Manage the tags belonging to one or more referenced images

**Usage**

```none theme={null}
cpln image tag <ref...> --tag KEY=VALUE [OPTIONS]
```

<Note>
  Built-in tags, which begin with cpln/\*, can't be modified.
</Note>

<Accordion title="Reference">
  ```text theme={null}
  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](/cli-reference/using-cli/common-options)
</Accordion>

<Accordion title="Example">
  * Add a tag

  <CodeGroup>
    ```bash Command theme={null}
    cpln image tag demo-image:1 --tag drink=water --org demo-cpln-organization
    ```

    ```text Output theme={null}
    +-------------+----------------------------------------------------------+-----------------+------------+--------------+
    |NAME         |PULL                                                      |DIGEST           |CREATED     |TAGS          |
    |-------------|----------------------------------------------------------|-----------------|------------|--------------|
    |demo-image:1 |demo-cpln-organization.registry.test.cpln.io/demo-image:1 |sha256:3fe719... |2 years ago |drink="water" |
    +-------------+----------------------------------------------------------+-----------------+------------+--------------+
    ```
  </CodeGroup>

  * Update same tag (after running the example above)

  <CodeGroup>
    ```bash Command theme={null}
    cpln image tag demo-image:1 --tag drink=coffee --org demo-cpln-organization
    ```

    ```text Output theme={null}
    +-------------+----------------------------------------------------------+-----------------+------------+---------------+
    |NAME         |PULL                                                      |DIGEST           |CREATED     |TAGS           |
    |-------------|----------------------------------------------------------|-----------------|------------|---------------|
    |demo-image:1 |demo-cpln-organization.registry.test.cpln.io/demo-image:1 |sha256:3fe719... |2 years ago |drink="coffee" |
    +-------------+----------------------------------------------------------+-----------------+------------+---------------+
    ```
  </CodeGroup>

  * Remove tag (after running the example above)

  <CodeGroup>
    ```bash Command theme={null}
    cpln image tag demo-image:1 --remove drink --org demo-cpln-organization
    ```

    ```text Output theme={null}
    +-------------+----------------------------------------------------------+-----------------+------------+-----+
    |NAME         |PULL                                                      |DIGEST           |CREATED     |TAGS |
    |-------------|----------------------------------------------------------|-----------------|------------|-----|
    |demo-image:1 |demo-cpln-organization.registry.test.cpln.io/demo-image:1 |sha256:3fe719... |2 years ago |     |
    +-------------+----------------------------------------------------------+-----------------+------------+-----+
    ```
  </CodeGroup>
</Accordion>

***