--- title: "Image CLI reference" description: "Customer-hosted cloud features" --- # Image CLI reference #### Customer-hosted cloud features :::note Some features are only available on customer-hosted clouds. Reach out to [support@anyscale.com](mailto:support@anyscale.com) for info. ::: ## Image CLI ### `anyscale image build` **Usage** `anyscale image build [OPTIONS]` Build an image from a Containerfile. **Options** - **`--containerfile/-f`**: Path to the Containerfile. - **`--name/-n`**: Name for the image. If the image with the same name already exists, a new version will be built. Otherwise, a new image will be created. - **`--ray-version/-r`**: The Ray version (X.Y.Z) specified for this image specified by either an image URI or a containerfile. If you don't specify a Ray version, Anyscale defaults to the latest Ray version available at the time of the Anyscale CLI/SDK release. - **`--cloud-id`**: The ID of the Anyscale Cloud. Required for Azure Control Plane only. #### Examples ::::tabs :::tab[CLI] ```bash $ anyscale image build -f my.Dockerfile -n my-image --ray-version 2.21.0 (anyscale +2.8s) Building image. View it in the UI: https://console.anyscale.com/v2/... (anyscale +1m53.0s) Waiting for image build to complete. Elapsed time: 102 seconds. (anyscale +1m53.0s) Image build succeeded. Image built successfully with URI: anyscale/image/my-image:1 $ cat my.Dockerfile FROM anyscale/ray:2.21.0-py39 RUN pip install --no-cache-dir pandas ``` ::: :::: ### `anyscale image get` **Usage** `anyscale image get [OPTIONS]` Get details of an image. **Options** - **`--name/-n`**: Get the details of an image. The name can contain an optional version, e.g., 'name:version'. If no version is provided, the latest one will be used. - **`-j/--json`**: Output as JSON. - **`--yaml`**: Output as YAML. - **`-v/--verbose`**: Show all fields including IDs and metadata. - **`--cloud-id`**: The ID of the Anyscale Cloud. Required for Azure Control Plane only. #### Examples ::::tabs :::tab[CLI] ```bash $ anyscale image get -n my-image uri: anyscale/image/my-image:1 status: SUCCEEDED ray_version: 2.21.0 ``` ::: :::: ### `anyscale image list` **Usage** `anyscale image list [OPTIONS]` List images. **Options** - **`--image-id/--id`**: ID of the image to display. - **`--name/-n`**: Substring to match against the image name. - **`--image-name`**: Substring to match against the resolved image URI (BYOD images only). - **`--project`**: Filter images by project name. - **`--created-by-me`**: List images created by me only. - **`--include-archived`**: Include archived images in the results. - **`--include-anonymous`**: Include anonymous (workspace-scoped) images. - **`--max-items`**: Max total items (only with --no-interactive). - **`--page-size`**: Items per page (max 50). - **`--interactive/--no-interactive`**: Use interactive paging. - **`-j/--json`**: Emit structured JSON to stdout. - **`-v/--verbose`**: Show all fields including IDs and metadata. - **`--cloud-id`**: The ID of the Anyscale Cloud. Required for Azure Control Plane only. #### Examples ::::tabs :::tab[CLI] ```bash $ anyscale image list --no-interactive --max-items 2 NAME LATEST VERSION LATEST URI CREATED BY CREATED AT my-image 3 anyscale/image/my-image:3 dhyey@anyscale.com 2024-12-01 18:42 workspace 1 anyscale/image/workspace:1 joshlee@anyscale.com 2024-11-09 09:15 ``` ::: :::: ### `anyscale image register` **Usage** `anyscale image register [OPTIONS]` Register a custom container image with a container image name. **Options** - **`--image-uri`**: The URI of the custom container image to register. - **`--name/-n`**: Name for the container image. If the name already exists, a new version will be built. Otherwise, a new container image will be created. - **`--ray-version/-r`**: The Ray version (X.Y.Z) specified for this image specified by either an image URI or a containerfile. If you don't specify a Ray version, Anyscale defaults to the latest Ray version available at the time of the Anyscale CLI/SDK release. - **`--registry-login-secret`**: Name or identifier of the secret containing credentials to authenticate to the docker registry hosting the image. - **`--cloud-id`**: The ID of the Anyscale Cloud to associate this image with. Required for Azure Control Plane only. #### Examples ::::tabs :::tab[CLI] ```bash $ anyscale image register --image-uri docker.io/myrepo/image:v2 --name mycoolimage --ray-version 2.30.0 Image registered successfully with URI: anyscale/image/mycoolimage:1 ``` ::: :::: ### `anyscale image archive` **Usage** `anyscale image archive [OPTIONS]` Archive an image and all of its versions. **Options** - **`--name/-n`**: Name of the image to archive. Can include an optional version tag (e.g., 'name:version'). - **`--cloud-id`**: The ID of the Anyscale Cloud. Required for Azure Control Plane only. #### Examples ::::tabs :::tab[CLI] ```bash $ anyscale image archive --name my-old-image (anyscale +0.5s) Successfully archived image. Image 'my-old-image' archived successfully. ``` ::: :::: ## Image models ### `ImageBuildStatus` Status of an image build operation. #### Values - **`IN_PROGRESS`**: The image build is in progress. - **`SUCCEEDED`**: The image build succeeded. - **`FAILED`**: The image build failed. - **`UNKNOWN`**: The CLI/SDK received an unexpected state from the API server. In most cases, this means you need to update the CLI. ### `ImageBuild` ImageBuild(id: str, name: str, project\_id: Optional\[str\] = None, creator\_id: Optional\[str\] = None, creator\_email: Optional\[str\] = None, is\_anonymous: bool = False, created\_at: Optional\[datetime.datetime\] = None, last\_modified\_at: Optional\[datetime.datetime\] = None, latest\_build\_id: Optional\[str\] = None, latest\_build\_revision: Optional\[int\] = None, latest\_build\_status: Union\[str, anyscale.image.models.ImageBuildStatus, NoneType\] = None, latest\_image\_uri: Optional\[str\] = None) #### Fields - **`id` (str)**: Unique identifier of the image. - **`name` (str)**: Human-readable name assigned to the image (cluster environment). - **`project_id` (str | None)**: Project identifier that owns this image, if available. - **`creator_id` (str | None)**: Identifier of the user who created the image. - **`creator_email` (str | None)**: Email address of the user who created the image, if available. - **`is_anonymous` (bool)**: Whether the image was created as an anonymous (workspace-scoped) resource. - **`created_at` (datetime | None)**: Timestamp when the image was created. - **`last_modified_at` (datetime | None)**: Timestamp when the image was last updated. - **`latest_build_id` (str | None)**: Identifier of the most recent build for this image. - **`latest_build_revision` (int | None)**: Revision number of the most recent image build (treated as the latest version). - **`latest_build_status` (str | [ImageBuildStatus](#imagebuildstatus) | None)**: Status of the most recent image build. - **`latest_image_uri` (str | None)**: URI for the latest published image version, if available. #### Python Methods ```python def to_dict(self) -> Dict[str, Any] """Return a dictionary representation of the model.""" ``` #### Examples ::::tabs :::tab[Python] ```python import anyscale from anyscale.image.models import ImageBuild first_image: ImageBuild = next(anyscale.image.list(max_items=1), None) ``` ::: :::: --- Previous: [Compute config](/reference/cli/compute-config.md) | Next: [Job queue](/reference/cli/job-queue.md)