Container Registry CLI Reference

The vercel vcr command group lets you manage Vercel Container Registry (VCR) repositories, tags, and images from your terminal. Use it to list, inspect, create, and delete repositories, browse a repository's tags, manage the images stored in each repository, and control which teams a repository is shared with.

vercel vcr is part of the Vercel CLI. Use vercel vcr build and vercel vcr push to build and push images, and see the Container Registry documentation for the end-to-end workflow. Both commands run your local container tool rather than replacing it, so the tool you choose must be installed and on your PATH.

Each command operates on a single Vercel project. By default, the CLI uses the linked project. Pass --project to target a different project.

Install the Vercel CLI globally to use the vercel vcr commands:

pnpm i -g vercel

yarn global add vercel

npm i -g vercel

bun add -g vercel

Log in to your Vercel account:

vercel login

Then link the directory to a Vercel project so the commands default to it:

vercel link

Manage Vercel Container Registry repositories and images.

vercel vcr <subcommand> [OPTIONS]

Available subcommands:

• ls: List container registry repositories for a project. (alias: list)
• inspect: Show details for a single repository. (alias: get)
• add: Create a container registry repository. (alias: create)
• rm: Delete a container registry repository. (aliases: remove, delete)
• login: Authenticate a container tool with the Vercel Container Registry.
• build: Build a container image tagged for the Vercel Container Registry.
• push: Push a container image to the Vercel Container Registry.
• tag: List or inspect a repository's tags. (alias: tags)
• image: List, inspect, or delete images in a repository. (alias: images)
• permissions: Manage which teams can pull images from a repository. (alias: permission)
• config: Configure a repository, such as its visibility.

For more help, try running vercel vcr <subcommand> --help.

List container registry repositories for a project.

vercel vcr ls [OPTIONS]

# List repositories in the linked project
vercel vcr ls
 
# List repositories for a specific project as JSON
vercel vcr ls --project my-app --format json
 
# Page through results using the cursor reported by the previous page
vercel vcr ls --cursor <token>

Show details for a single repository.

vercel vcr inspect [OPTIONS] <repository>

# Inspect a repository by name
vercel vcr inspect my-repository
 
# Inspect a repository by ID
vercel vcr inspect repo_CVSY2AmyvugNN6WOTFKOF5VfeZ6r

Create a container registry repository.

vercel vcr add [OPTIONS] <name>

# Create a repository
vercel vcr add my-repository

Delete a container registry repository and all of its images.

vercel vcr rm [OPTIONS] <repository>

# Delete a repository, with a confirmation prompt
vercel vcr rm my-repository
 
# Delete a repository without the confirmation prompt
vercel vcr rm my-repository --yes

Authenticate a container tool (Docker, Podman, or Buildah) with the Vercel Container Registry.

vercel vcr login [OPTIONS] <engine>

Vercel mints a short-lived, project-scoped OpenID Connect (OIDC) token and passes it to the container tool with the username oidc. The credentials are valid for 12 hours. Re-run the command to refresh them.

The container tool must be installed and on your PATH. If it isn't, the command fails with an error like `docker` is not installed or not on your PATH. Install it and try again.

# Log in with Docker
vercel vcr login docker
 
# Log in with Podman
vercel vcr login podman
 
# Log in with Buildah
vercel vcr login buildah
 
# Log in for a specific project
vercel vcr login docker --project my-app

Build a container image tagged for the Vercel Container Registry by running your container tool (Docker, Podman, or Buildah).

vercel vcr build [OPTIONS] <engine> [path] [name]

The build context defaults to the current directory, the repository to the project name, and the tag to latest, so vercel vcr build docker tags vcr.vercel.com/<team-slug>/<project-name>/<project-name>:latest. For the [name] argument, pass only a repository name, optionally with :tag. The CLI adds the registry, team, and project segments and rejects a name containing /.

--push uploads the image after building.

Anything after -- is forwarded to the container tool unchanged.

# Build the current directory into the linked project
vercel vcr build docker
 
# Build and push in one step
vercel vcr build docker --push
 
# Build a specific context path with a repository and tag
vercel vcr build docker ./app my-api:1.2.3
 
# Pass extra flags through to the container tool
vercel vcr build docker . -- --no-cache --build-arg KEY=value

Push a container image to the Vercel Container Registry by running your container tool (Docker, Podman, or Buildah).

vercel vcr push [OPTIONS] <engine> [name]

The image must already exist locally, built by vercel vcr build or tagged for VCR yourself. push resolves the same defaults as build, so pass the same name[:tag] you built with. Podman and Buildah push with zstd compression. Docker can't compress on a plain push, so use vercel vcr build docker --push with Buildx for zstd.

Anything after -- is forwarded to the container tool unchanged.

# Push the linked project image
vercel vcr push docker
 
# Push a specific repository and tag
vercel vcr push docker my-api:1.2.3

List or inspect a repository's tags.

vercel vcr tag <subcommand> [OPTIONS]

• ls: List a repository's tags. (alias: list)
• inspect: Show details for a single tag. (alias: get)

List a repository's tags.

vercel vcr tag ls [OPTIONS] <repository>

# List a repository's tags
vercel vcr tag ls my-app
 
# Sort by tag name in ascending order
vercel vcr tag ls my-app --sort-by tag --sort-order asc
 
# Return the first five tags
vercel vcr tag ls my-app --limit 5

Show details for a single tag.

vercel vcr tag inspect [OPTIONS] <repository> <tag>

# Inspect a tag by name
vercel vcr tag inspect my-app latest

List, inspect, or delete images in a repository.

vercel vcr image <subcommand> [OPTIONS]

• ls: List images in a container registry repository. (alias: list)
• inspect: Show details for a single image, including its layer history. (alias: get)
• rm: Delete an image from a repository. (aliases: remove, delete)

List images in a container registry repository.

vercel vcr image ls [OPTIONS] <repository>

# List images in a repository
vercel vcr image ls my-app
 
# List only untagged images as JSON
vercel vcr image ls my-app --untagged --format json

Show details for a single image, including its layer history.

vercel vcr image inspect [OPTIONS] <repository> <image-id>

# Inspect an image by ID
vercel vcr image inspect my-app image_XTPv9FRCWob68TkdGMUHC9vCXIAz

Delete an image from a repository.

vercel vcr image rm [OPTIONS] <repository> <image-id>

# Delete an image by ID, with a confirmation prompt
vercel vcr image rm my-app image_Ml0PUBaNT8SRrYXDOOEiFedAsAEs
 
# Delete an image without the confirmation prompt
vercel vcr image rm my-app image_Ml0PUBaNT8SRrYXDOOEiFedAsAEs --yes

Manage which teams can pull images from a container registry repository. See Share a repository for how sharing works.

vercel vcr permissions <repository> <subcommand> [OPTIONS]

Unlike vercel vcr tag and vercel vcr image, the repository comes before the subcommand.

• ls: List teams with access to a repository. (alias: list)
• add: Give one or more teams access to pull images from a repository.
• rm: Remove one or more teams' access to a repository. (alias: remove)
• clear: Remove access to a repository for every team.

List the teams a repository is shared with, and when each team was added.

vercel vcr permissions <repository> ls [OPTIONS]

# List teams with access to a repository
vercel vcr permissions my-repository ls
 
# List teams with access as JSON
vercel vcr permissions my-repository ls --format json

Give one or more teams access to pull images from a repository.

vercel vcr permissions <repository> add <team> [OPTIONS]

Teams that start with team_ are treated as team IDs. Anything else is treated as a team slug.

# Share a repository with a team by ID
vercel vcr permissions my-repository add team_1a2b3c4d
 
# Share a repository with a team by slug
vercel vcr permissions my-repository add my-team
 
# Share a repository with multiple teams
vercel vcr permissions my-repository add team_1a2b3c4d,other-team

Remove one or more teams' access to a repository.

vercel vcr permissions <repository> rm <team> [OPTIONS]

# Remove a team's access by ID
vercel vcr permissions my-repository rm team_1a2b3c4d
 
# Remove multiple teams' access
vercel vcr permissions my-repository rm team_1a2b3c4d,other-team

Remove access to a repository for every team.

vercel vcr permissions <repository> clear [OPTIONS]

# Clear all repository permissions, with a confirmation prompt
vercel vcr permissions my-repository clear
 
# Clear all repository permissions without the confirmation prompt
vercel vcr permissions my-repository clear --yes

Configure a container registry repository, such as the repository's visibility. See Public Repositories for how visibility works.

vercel vcr config <repository> [OPTIONS]

# Make a repository public
vercel vcr config my-repository --public true
 
# Make a repository private without revoking access for shared teams
vercel vcr config my-repository --public false