Depot CLI: Registry commands

Use depot registry to manage your organization's Depot Registry. Install the Depot CLI and supply an organization API token with DEPOT_TOKEN or --token. The token selects the organization. These commands don't use the stored depot login token.

Commands return JSON. Repository arguments are paths such as team/app, without a registry hostname, organization prefix, tag, or digest. For images saved by container builds, use the separate depot image commands.

Delete, revoke, and retention-set commands require --yes. They return an error without it instead of prompting.

depot registry repository

Create, list, and delete repositories. repositories is an alias for repository.

depot registry repository list

List one page of repositories. --page starts at 1. --page-size defaults to 25 and accepts 1–100. Use --query to filter repository names. The JSON response includes pagination metadata.

depot registry repository list --query team/ --page 1 --page-size 50

depot registry repository create

Create a repository:

depot registry repository create team/app

For a pull-through repository, supply an upstream ID and its repository path:

depot registry repository create team/base --upstream-id <upstream-id> --upstream-repository library/alpine

depot registry repository delete

Delete a repository and its images:

depot registry repository delete team/old-app --yes

depot registry image

List, inspect, and delete repository images. images is an alias for image.

depot registry image list

List one page of images in a repository. Use --query to filter tags and --tag-status to select all, tagged, or untagged. Pagination uses --page and --page-size, with the same defaults and limits as repository listing.

depot registry image list team/app --tag-status tagged --query release --page-size 50

depot registry image inspect

Inspect an image by tag or digest. The manifest bytes are base64-encoded in the JSON response.

depot registry image inspect team/app latest

depot registry image delete

Delete images using one or more --tag or --digest flags. Deleting a digest removes all its associated tags.

depot registry image delete team/app --tag old-release --tag staging --yes

The JSON response includes individual deletion failures. If any image fails to delete, the command exits with an error after printing the response; other images may already have been deleted.

depot registry tag

Manage the tags attached to repository images.

depot registry tag delete

Remove a tag from an image:

depot registry tag delete team/app old-release --yes

depot registry token

Manage registry pull/push credentials. tokens is an alias for token.

depot registry token create

Create a scoped registry token. Token creation through an organization API token must be enabled for your organization. The response prints the new secret once; store it securely.

depot registry token create release-pull --permission pull --scope 'team/*'

depot registry token list

List token metadata without secrets. --query, --page, and --page-size work as they do for repository listing.

depot registry token list --query release

depot registry token revoke

Revoke a registry token by ID:

depot registry token revoke <token-id> --yes

depot registry retention

Manage explicit retention policies for a repository path or pattern. Quote * and ** to prevent shell expansion.

depot registry retention get

Read the explicit policy for a scope. This does not resolve inherited policies.

depot registry retention get team/app
depot registry retention get '**'

depot registry retention set

Set exactly one positive --keep-count or --keep-days value. Changing retention can delete older images.

depot registry retention set team/app --keep-count 10 --yes

To retain images by age instead:

depot registry retention set team/app --keep-days 14 --yes

depot registry retention delete

Remove an explicit policy. An inherited policy can still apply, and previously deleted images aren't restored.

depot registry retention delete team/app --yes

depot registry upstream

Manage upstream registries for pull-through caching. upstreams is an alias for upstream.

depot registry upstream list

List upstream registry configurations. Passwords are never returned.

depot registry upstream list

depot registry upstream create

Create an upstream with --url. Basic authentication is the default; supply --username and --password-stdin when credentials are needed. For example, read a password from a protected file:

depot registry upstream create private-images --url registry.example.com --username <username> --password-stdin < password.txt

For ECR, use --auth-type ecr --role-arn <role-arn> instead of username/password credentials. Configure the AWS role as described in the ECR upstream guide. Don't include credentials in --url.

depot registry upstream update

Update only the fields you supply: --url, --username, --role-arn, or --password-stdin. An explicitly empty username or password clears that value. Authentication type cannot be changed with this command.

depot registry upstream update <upstream-id> --password-stdin < password.txt

depot registry upstream delete

Delete an upstream registry configuration:

depot registry upstream delete <upstream-id> --yes