crane-delete

Delete an image reference from its registry

$ crane delete [image_name]

$ crane delete [[-h|--help]]

crane delete [OPTIONS] REF

--allow-missing
    Don't fail if the manifest or tag doesn't exist

--ensure-empty
    Ensure the repository becomes empty after deletion (fails otherwise)

--insecure
    Allow connection to HTTP registry; do not verify TLS

--platform PLATFORM
    Delete only the manifest matching the specified platform (e.g., linux/amd64)

--registry-mirror URL
    Use the given registry mirror

--timeout DURATION
    Timeout for registry operations (default: 1m)

The crane delete command is part of the crane CLI tool, developed for efficient manipulation of OCI container images and artifacts directly from container registries without downloading full images. It specifically targets the deletion of image manifests or tags from remote repositories.

This command interacts with registry APIs to remove specified references, supporting multi-platform manifests and lists. It's useful for cleaning up unused images, enforcing retention policies, or managing registry storage. Unlike docker rmi, which operates on local images, crane delete works purely remotely, making it ideal for CI/CD pipelines and air-gapped environments where full pulls are impractical.

Key features include selective deletion by platform, handling missing manifests gracefully, and ensuring repositories are emptied. It requires appropriate registry permissions (typically write/delete scopes) and supports insecure HTTP registries for private setups. Usage involves specifying the full image reference (e.g., registry.example.com/repo:tag), with options for fine-tuned control.

Requires delete permissions on the registry; does not garbage-collect layers automatically; multi-arch images may leave dangling blobs.

Supports standard docker login creds or CRANE_AUTH env vars; OIDC tokens via flags.

0 on success; 1 for permission errors; 2 for invalid args; 4 for not found.

Developed by Google as part of the crane toolset (v0.1+ in 2021), inspired by imgpkg and kosmos. Actively maintained under Apache-2.0 for OCI compliance; gained popularity with Sigstore/cosign integration.

crane(1), skopeo(1), docker-rmi(1), regctl(1)