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

# sandboximage

> cpln sandboximage: Build and manage sandbox images, the custom images that dev sandboxes and sandbox sessions run.

Manage sandbox images

For a detailed overview, please visit the [sandbox image's](https://docs.controlplane.com/reference/sandbox/image.md) reference page.

Refer to the [sandbox images guide](https://docs.controlplane.com/guides/sandbox/sandbox-images.md) for additional details.

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

```text theme={null}
Commands:
  cpln sandboximage access-report <ref>  Show the access report for the referenced sandbox image
  cpln sandboximage audit [ref]          Retrieve audit trail events for the referenced sandbox image
  cpln sandboximage buildlog <ref>       Print the referenced sandbox image's latest build log
  cpln sandboximage clone <ref>          Create a copy of the referenced sandbox image; the copy builds under your token  [aliases: copy]
  cpln sandboximage create               Create a sandbox image and submit its build
  cpln sandboximage delete <ref...>      Delete one or more referenced sandbox images
  cpln sandboximage edit <ref>           Edit the referenced sandbox image, as YAML, within an editor
  cpln sandboximage eventlog <ref>       Show the event log of the referenced sandbox image  [aliases: log]
  cpln sandboximage get [ref...]         Retrieve one or more referenced sandbox images
  cpln sandboximage patch <ref>          Update the referenced sandbox image's metadata using an input file
  cpln sandboximage permissions          Show the grantable permissions for a sandbox image object type
  cpln sandboximage query                Find all the sandbox images based on the given query
  cpln sandboximage rebuild <ref...>     Rebuild one or more referenced sandbox images from their current recipe
  cpln sandboximage tag <ref...>         Manage the tags belonging to one or more referenced sandbox images
  cpln sandboximage update <ref>         Update properties of the referenced sandbox image

Options:
  --help  Show help  [boolean]
```

***

#### sandboximage access-report

Show the access report for the referenced sandbox image

**Usage**

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

> [accordion] Reference
>
> ```text theme={null}
> Positionals:
>   ref  The resource reference. Usually it is the name of the resource.  [required]
>
> 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]
>
> 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
>
> Options:
>   --help  Show help  [boolean]
> ```
>
> [Common Options Reference](https://docs.controlplane.com/cli-reference/using-cli/common-options.md)

> [accordion] Example
>
> ```bash Command theme={null}
> cpln sandboximage access-report demo-sandbox-image --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  |
> |view       |/org/demo-cpln-organization/group/viewers               |view    |
> |view       |/org/demo-cpln-organization/group/superusers            |manage  |
> |view       |/org/demo-cpln-organization/serviceaccount/controlplane |manage  |
> +-----------+--------------------------------------------------------+--------+
> ```

***

#### sandboximage audit

Retrieve audit trail events for the referenced sandbox image

**Usage**

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

> [accordion] 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]
>
> 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]
>
> 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
>
> Options:
>   --help  Show help  [boolean]
> ```
>
> [Common Options Reference](https://docs.controlplane.com/cli-reference/using-cli/common-options.md)

> [accordion] Example
>
> * Show the audit trail events of a sandbox image from the last 7 days (the default)
>
> ```bash theme={null}
> cpln sandboximage audit demo-sandbox-image --org demo-cpln-organization
> ```
>
> * Show the audit trail events of a sandbox image from the last 24 hours
>
> ```bash theme={null}
> cpln sandboximage audit demo-sandbox-image --since 24h --org demo-cpln-organization
> ```

***

#### sandboximage buildlog

Print the referenced sandbox image's latest build log

**Usage**

```none theme={null}
cpln sandboximage buildlog <ref> [OPTIONS]
```

> [accordion] Reference
>
> ```text theme={null}
> Positionals:
>   ref  The resource reference. Usually it is the name of the resource.  [required]
>
> Command options:
>   --follow, -t, -f  Keep reading until the build ends, waiting for a build not yet submitted. Without it, the log read so far is printed.  [boolean] [default: false]
>   --offset          The byte offset to start from, for a read that resumes an earlier one.  [number] [default: 0]
>
> 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](https://docs.controlplane.com/cli-reference/using-cli/common-options.md)

> [accordion] Example
>
> * Print the log of the latest build as read so far
>
> ```bash theme={null}
> cpln sandboximage buildlog demo-sandbox-image --org demo-cpln-organization
> ```
>
> * Keep reading the log until the build ends
>
> ```bash theme={null}
> cpln sandboximage buildlog demo-sandbox-image --follow --org demo-cpln-organization
> ```

***

#### sandboximage clone

Create a copy of the referenced sandbox image; the copy builds under your token

**Usage**

```none theme={null}
cpln sandboximage clone <ref> --name CLONE_NAME [OPTIONS]
```

> [accordion] Reference
>
> ```text theme={null}
> Positionals:
>   ref  The resource reference. Usually it is the name of the resource.  [required]
>
> Command options:
>   --name         Set the name for the clone  [required]
>   --description  Optional description, defaults to the name if not set
>   --tag          Attach tags (e.g., --tag drink=water)
>   --dry-run      Validate the request and print the resource that would be written, without writing it. Defaults the output format to yaml-slim  [boolean]
>
> 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]
>
> 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
>
> Options:
>   --help  Show help  [boolean]
> ```
>
> [Common Options Reference](https://docs.controlplane.com/cli-reference/using-cli/common-options.md)

> [accordion] Example
>
> ```bash Command theme={null}
> cpln sandboximage clone demo-sandbox-image --name demo-sandbox-image-clone --org demo-cpln-organization
> ```
>
> ```text Output theme={null}
> +-------------------------+-------------------------+-----+--------+------+-------------------------+-----+
> |NAME                     |DESCRIPTION              |TYPE |PHASE   |IMAGE |BASE                     |TAGS |
> |-------------------------|-------------------------|-----|--------|------|-------------------------|-----|
> |demo-sandbox-image-clone |demo-sandbox-image-clone |dev  |pending |      |//image/demo-base:latest |     |
> +-------------------------+-------------------------+-----+--------+------+-------------------------+-----+
> ```

***

#### sandboximage create

Create a sandbox image and submit its build

**Usage**

```none theme={null}
cpln sandboximage create --name SANDBOX_IMAGE_NAME [OPTIONS]
```

> [!NOTE]
>
> The command returns as soon as the build is submitted. Follow the build with [sandboximage buildlog](#sandboximage-buildlog), and read its phase with [sandboximage get](#sandboximage-get).

> [!TIP]
>
> `--type dev`, the default, builds an image for dev sandboxes. `--type agent` builds an image for sessions and needs `--base-image`.

> [accordion] Reference
>
> ```text theme={null}
> Command options:
>   --name                 The name of the new sandbox image.  [required]
>   --description, --desc  Optional description, defaults to the name if not set.
>   --base-image           The image the sandbox layer is built onto: a link to an org image (//image/<name>:<tag>) or a full image reference. Omit it to build on the standard sandbox base. Build one with 'cpln image build'.
>   --image-tag            The tag of the built image in the org registry. Defaults to latest.
>   --type                 dev (default) builds the base plus the sandbox layer, for dev sandboxes; agent copies the base alone, for sessions, and needs --base-image.  [choices: "dev", "agent"]
>   --tag                  Attach tags (e.g., --tag drink=water)
>   --dry-run              Validate the request and print the resource that would be written, without writing it. Defaults the output format to yaml-slim  [boolean]
>
> 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](https://docs.controlplane.com/cli-reference/using-cli/common-options.md)

> [accordion] Example
>
> * Create a dev sandbox image on the standard sandbox base
>
> ```bash Command theme={null}
> cpln sandboximage create --name demo-standard-image --org demo-cpln-organization
> ```
>
> ```text Output theme={null}
> +--------------------+--------------------+-----+--------+------+---------+-----+
> |NAME                |DESCRIPTION         |TYPE |PHASE   |IMAGE |BASE     |TAGS |
> |--------------------|--------------------|-----|--------|------|---------|-----|
> |demo-standard-image |demo-standard-image |dev  |pending |      |standard |     |
> +--------------------+--------------------+-----+--------+------+---------+-----+
> ```
>
> * Create a dev sandbox image on an image of the org, and tag the built image `v1`
>
> ```bash Command theme={null}
> cpln sandboximage create --name demo-sandbox-image --base-image //image/demo-base:latest --image-tag v1 --org demo-cpln-organization
> ```
>
> ```text Output theme={null}
> +-------------------+-------------------+-----+--------+------+-------------------------+-----+
> |NAME               |DESCRIPTION        |TYPE |PHASE   |IMAGE |BASE                     |TAGS |
> |-------------------|-------------------|-----|--------|------|-------------------------|-----|
> |demo-sandbox-image |demo-sandbox-image |dev  |pending |      |//image/demo-base:latest |     |
> +-------------------+-------------------+-----+--------+------+-------------------------+-----+
> ```
>
> * Create an agent sandbox image, for sessions
>
> ```bash Command theme={null}
> cpln sandboximage create --name demo-agent-image --type agent --base-image //image/demo-agent-base:latest --org demo-cpln-organization
> ```
>
> ```text Output theme={null}
> +-----------------+-----------------+------+--------+------+-------------------------------+-----+
> |NAME             |DESCRIPTION      |TYPE  |PHASE   |IMAGE |BASE                           |TAGS |
> |-----------------|-----------------|------|--------|------|-------------------------------|-----|
> |demo-agent-image |demo-agent-image |agent |pending |      |//image/demo-agent-base:latest |     |
> +-----------------+-----------------+------+--------+------+-------------------------------+-----+
> ```

***

#### sandboximage delete

Delete one or more referenced sandbox images

**Usage**

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

> [accordion] Reference
>
> ```text theme={null}
> Positionals:
>   ref  One or more resource references. Usually it is the name of the resource.  [array] [required] [default: []]
>
> 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]
>
> 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
>
> Options:
>   --help  Show help  [boolean]
> ```
>
> [Common Options Reference](https://docs.controlplane.com/cli-reference/using-cli/common-options.md)

> [accordion] Example
>
> ```bash Command theme={null}
> cpln sandboximage delete demo-sandbox-image --org demo-cpln-organization
> ```
>
> ```text Output theme={null}
> If the delete was successful, a new command prompt will be shown.
> ```

***

#### sandboximage edit

Edit the referenced sandbox image, as YAML, within an editor

**Usage**

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

> [!NOTE]
>
> The default editor can be set by using the EDITOR environment variable.

> [accordion] 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]
>   --dry-run      Validate the request and print the resource that would be written, without writing it. Defaults the output format to yaml-slim  [boolean]
>
> 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]
>
> 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
>
> Options:
>   --help  Show help  [boolean]
> ```
>
> [Common Options Reference](https://docs.controlplane.com/cli-reference/using-cli/common-options.md)

> [accordion] Example
>
> ```bash Command theme={null}
> cpln sandboximage edit demo-sandbox-image --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.
> ```

***

#### sandboximage eventlog

Show the event log of the referenced sandbox image

**Usage**

```none theme={null}
cpln sandboximage eventlog <ref> [OPTIONS]
```

> [accordion] Reference
>
> ```text theme={null}
> Positionals:
>   ref  The resource reference. Usually it is the name of the resource.  [required]
>
> 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]
>
> 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
>
> Options:
>   --help  Show help  [boolean]
> ```
>
> [Common Options Reference](https://docs.controlplane.com/cli-reference/using-cli/common-options.md)

> [accordion] Example
>
> ```bash Command theme={null}
> cpln sandboximage eventlog demo-sandbox-image --org demo-cpln-organization
> ```
>
> ```text Output theme={null}
> The event log for the referenced sandbox image will be shown.
> ```

***

#### sandboximage get

Retrieve one or more referenced sandbox images

**Usage**

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

> [!NOTE]
>
> An empty reference will return all references

> [accordion] Reference
>
> ```text theme={null}
> Positionals:
>   ref  One or more resource references. Usually it is the name of the resource.  [array] [default: []]
>
> 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]
>
> 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
>
> Options:
>   --help  Show help  [boolean]
> ```
>
> [Common Options Reference](https://docs.controlplane.com/cli-reference/using-cli/common-options.md)

> [accordion] Example
>
> * Get all sandbox images
>
> ```bash Command theme={null}
> cpln sandboximage get --org demo-cpln-organization
> ```
>
> ```text Output theme={null}
> +-------------------+-------------------+------+---------+--------------------------------------------------------------+-------------------------------+-----+
> |NAME               |DESCRIPTION        |TYPE  |PHASE    |IMAGE                                                         |BASE                           |TAGS |
> |-------------------|-------------------|------|---------|--------------------------------------------------------------|-------------------------------|-----|
> |demo-agent-image   |demo-agent-image   |agent |building |                                                              |//image/demo-agent-base:latest |     |
> |demo-sandbox-image |demo-sandbox-image |dev   |ready    |demo-cpln-organization.registry.cpln.io/demo-sandbox-image:v1 |//image/demo-base:latest       |     |
> +-------------------+-------------------+------+---------+--------------------------------------------------------------+-------------------------------+-----+
> ```
>
> * Get one sandbox image
>
> ```bash Command theme={null}
> cpln sandboximage get demo-sandbox-image --org demo-cpln-organization
> ```
>
> ```text Output theme={null}
> +-------------------+-------------------+-----+------+--------------------------------------------------------------+-------------------------+-----+
> |NAME               |DESCRIPTION        |TYPE |PHASE |IMAGE                                                         |BASE                     |TAGS |
> |-------------------|-------------------|-----|------|--------------------------------------------------------------|-------------------------|-----|
> |demo-sandbox-image |demo-sandbox-image |dev  |ready |demo-cpln-organization.registry.cpln.io/demo-sandbox-image:v1 |//image/demo-base:latest |     |
> +-------------------+-------------------+-----+------+--------------------------------------------------------------+-------------------------+-----+
> ```

***

#### sandboximage patch

Update the referenced sandbox image's metadata using an input file

**Usage**

```none theme={null}
cpln sandboximage 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).

> [accordion] 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]
>   --dry-run   Validate the request and print the resource that would be written, without writing it. Defaults the output format to yaml-slim  [boolean]
>
> 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]
>
> 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
>
> Options:
>   --help  Show help  [boolean]
> ```
>
> [Common Options Reference](https://docs.controlplane.com/cli-reference/using-cli/common-options.md)

> [accordion] Example
>
> ```bash Command theme={null}
> cpln sandboximage patch demo-sandbox-image --file update.json --org demo-cpln-organization
> ```
>
> ```text Output theme={null}
> The changes within the JSON file will be performed against the referenced sandbox image.
> ```

***

#### sandboximage permissions

Show the grantable permissions for a sandbox image object type

**Usage**

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

> [accordion] Reference
>
> ```text theme={null}
> 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]
>
> 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
>
> Options:
>   --help  Show help  [boolean]
> ```
>
> [Common Options Reference](https://docs.controlplane.com/cli-reference/using-cli/common-options.md)

> [accordion] Example
>
> ```bash Command theme={null}
> cpln sandboximage permissions --org demo-cpln-organization
> ```
>
> ```text Output theme={null}
> +-------+-------------------------------+-----------------------------------+
> |NAME   |DESCRIPTION                    |IMPLIES                            |
> |-------|-------------------------------|-----------------------------------|
> |create |Create new sandbox images      |                                   |
> |delete |Delete existing sandbox images |                                   |
> |edit   |Modify existing sandbox images |view                               |
> |manage |Full access                    |create, delete, edit, manage, view |
> |view   |Read-only access               |                                   |
> +-------+-------------------------------+-----------------------------------+
> ```

***

#### sandboximage query

Find all the sandbox images based on the given query

**Usage**

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

> [accordion] 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
>
> 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]
>
> 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
>
> Options:
>   --help  Show help  [boolean]
> ```
>
> [Common Options Reference](https://docs.controlplane.com/cli-reference/using-cli/common-options.md)

> [accordion] Example
>
> > [!NOTE]
> >
> > Use the `--match` option to display **all**, **none**, or **any** of the results based on a given property or tag
>
> * Search for a sandbox image based on the name property
>
> ```bash Command theme={null}
> cpln sandboximage query --match any --prop name=demo-sandbox-image --org demo-cpln-organization
> ```
>
> ```text Output theme={null}
> +-------------------+-------------------+-----+------+--------------------------------------------------------------+-------------------------+-----+
> |NAME               |DESCRIPTION        |TYPE |PHASE |IMAGE                                                         |BASE                     |TAGS |
> |-------------------|-------------------|-----|------|--------------------------------------------------------------|-------------------------|-----|
> |demo-sandbox-image |demo-sandbox-image |dev  |ready |demo-cpln-organization.registry.cpln.io/demo-sandbox-image:v1 |//image/demo-base:latest |     |
> +-------------------+-------------------+-----+------+--------------------------------------------------------------+-------------------------+-----+
> ```
>
> * Search for the sandbox images whose latest build is ready
>
> ```bash Command theme={null}
> cpln sandboximage query --prop status.phase=ready --org demo-cpln-organization
> ```
>
> ```text Output theme={null}
> +-------------------+-------------------+-----+------+--------------------------------------------------------------+-------------------------+-----+
> |NAME               |DESCRIPTION        |TYPE |PHASE |IMAGE                                                         |BASE                     |TAGS |
> |-------------------|-------------------|-----|------|--------------------------------------------------------------|-------------------------|-----|
> |demo-sandbox-image |demo-sandbox-image |dev  |ready |demo-cpln-organization.registry.cpln.io/demo-sandbox-image:v1 |//image/demo-base:latest |     |
> +-------------------+-------------------+-----+------+--------------------------------------------------------------+-------------------------+-----+
> ```

***

#### sandboximage rebuild

Rebuild one or more referenced sandbox images from their current recipe

**Usage**

```none theme={null}
cpln sandboximage rebuild <ref...> [OPTIONS]
```

> [accordion] Reference
>
> ```text theme={null}
> Positionals:
>   ref  One or more resource references. Usually it is the name of the resource.  [array] [required] [default: []]
>
> Command options:
>   --dry-run  Validate the request and print the resource that would be written, without writing it. Defaults the output format to yaml-slim  [boolean]
>
> 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](https://docs.controlplane.com/cli-reference/using-cli/common-options.md)

> [accordion] Example
>
> ```bash Command theme={null}
> cpln sandboximage rebuild demo-sandbox-image --org demo-cpln-organization
> ```
>
> ```text Output theme={null}
> +-------------------+-------------------+-----+--------+--------------------------------------------------------------+-------------------------+-----+
> |NAME               |DESCRIPTION        |TYPE |PHASE   |IMAGE                                                         |BASE                     |TAGS |
> |-------------------|-------------------|-----|--------|--------------------------------------------------------------|-------------------------|-----|
> |demo-sandbox-image |demo-sandbox-image |dev  |pending |demo-cpln-organization.registry.cpln.io/demo-sandbox-image:v1 |//image/demo-base:latest |     |
> +-------------------+-------------------+-----+--------+--------------------------------------------------------------+-------------------------+-----+
> ```

***

#### sandboximage tag

Manage the tags belonging to one or more referenced sandbox images

**Usage**

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

> [!NOTE]
>
> Built-in tags, which begin with cpln/\*, can't be modified.

> [accordion] 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)
>   --dry-run     Validate the request and print the resource that would be written, without writing it. Defaults the output format to yaml-slim  [boolean]
>
> 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]
>
> 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
>
> Options:
>   --help  Show help  [boolean]
> ```
>
> [Common Options Reference](https://docs.controlplane.com/cli-reference/using-cli/common-options.md)

> [accordion] Example
>
> * Add a tag
>
> ```bash Command theme={null}
> cpln sandboximage tag demo-sandbox-image --tag drink=water --org demo-cpln-organization
> ```
>
> ```text Output theme={null}
> +-------------------+-------------------+-----+------+--------------------------------------------------------------+-------------------------+--------------+
> |NAME               |DESCRIPTION        |TYPE |PHASE |IMAGE                                                         |BASE                     |TAGS          |
> |-------------------|-------------------|-----|------|--------------------------------------------------------------|-------------------------|--------------|
> |demo-sandbox-image |demo-sandbox-image |dev  |ready |demo-cpln-organization.registry.cpln.io/demo-sandbox-image:v1 |//image/demo-base:latest |drink="water" |
> +-------------------+-------------------+-----+------+--------------------------------------------------------------+-------------------------+--------------+
> ```
>
> * Remove tag (after running the example above)
>
> ```bash Command theme={null}
> cpln sandboximage tag demo-sandbox-image --remove-tag drink --org demo-cpln-organization
> ```
>
> ```text Output theme={null}
> +-------------------+-------------------+-----+------+--------------------------------------------------------------+-------------------------+-----+
> |NAME               |DESCRIPTION        |TYPE |PHASE |IMAGE                                                         |BASE                     |TAGS |
> |-------------------|-------------------|-----|------|--------------------------------------------------------------|-------------------------|-----|
> |demo-sandbox-image |demo-sandbox-image |dev  |ready |demo-cpln-organization.registry.cpln.io/demo-sandbox-image:v1 |//image/demo-base:latest |     |
> +-------------------+-------------------+-----+------+--------------------------------------------------------------+-------------------------+-----+
> ```

***

#### sandboximage update

Update properties of the referenced sandbox image

**Usage**

```none theme={null}
cpln sandboximage update <ref> --set UPDATE_PROPERTY [OPTIONS]
```

> [!NOTE]
>
> A change to a property under `spec` submits a new build of the sandbox image.

> [accordion] Reference
>
> ```text theme={null}
> Positionals:
>   ref  The resource reference. Usually it is the name of the resource.  [required]
>
> Update Properties:
>   --set    Update the following properties (e.g., --set description="Updated Description"):
>
>            description        string
>            tags.<key>         string
>            spec.base.image    string
>            spec.tag           string
>            spec.type          { 'dev' | 'agent' }
>   --unset  Unset a property (same paths as --set, e.g., --unset description)
>
> Command options:
>   --dry-run  Validate the request and print the resource that would be written, without writing it. Defaults the output format to yaml-slim  [boolean]
>
> 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]
>
> 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
>
> Options:
>   --help  Show help  [boolean]
> ```
>
> [Common Options Reference](https://docs.controlplane.com/cli-reference/using-cli/common-options.md)

> [accordion] Options
>
> * The `--set` option allows the modification of the following sandbox image properties:
>   * `description`
>     * Description of the sandbox image
>     * Type: string
>   * `tags`
>     * Tags (key=value) associated with the sandbox image
>     * Type: string
>   * `spec.base.image`
>     * The image the sandbox layer is built onto: a link to an org image (`//image/NAME:TAG`) or a full image reference
>     * Type: string
>   * `spec.tag`
>     * The tag of the built image in the org registry
>     * Default: latest
>     * Type: string
>   * `spec.type`
>     * The type of the sandbox image
>     * Choices: `dev`, `agent`
>     * Default: dev
>     * Type: string

> [accordion] Example
>
> * Update a sandbox image's description
>
> ```bash Command theme={null}
> cpln sandboximage update demo-sandbox-image --set description="Demo sandbox image" --org demo-cpln-organization
> ```
>
> ```text Output theme={null}
> +-------------------+-------------------+-----+------+--------------------------------------------------------------+-------------------------+-----+
> |NAME               |DESCRIPTION        |TYPE |PHASE |IMAGE                                                         |BASE                     |TAGS |
> |-------------------|-------------------|-----|------|--------------------------------------------------------------|-------------------------|-----|
> |demo-sandbox-image |Demo sandbox image |dev  |ready |demo-cpln-organization.registry.cpln.io/demo-sandbox-image:v1 |//image/demo-base:latest |     |
> +-------------------+-------------------+-----+------+--------------------------------------------------------------+-------------------------+-----+
> ```
>
> * Update a sandbox image's base image, which submits a new build
>
> ```bash Command theme={null}
> cpln sandboximage update demo-sandbox-image --set spec.base.image=//image/demo-base:v2 --org demo-cpln-organization
> ```
>
> ```text Output theme={null}
> +-------------------+-------------------+-----+--------+--------------------------------------------------------------+---------------------+-----+
> |NAME               |DESCRIPTION        |TYPE |PHASE   |IMAGE                                                         |BASE                 |TAGS |
> |-------------------|-------------------|-----|--------|--------------------------------------------------------------|---------------------|-----|
> |demo-sandbox-image |demo-sandbox-image |dev  |pending |demo-cpln-organization.registry.cpln.io/demo-sandbox-image:v1 |//image/demo-base:v2 |     |
> +-------------------+-------------------+-----+--------+--------------------------------------------------------------+---------------------+-----+
> ```

***
