Depot CLI: Container builds commands reference

Reference for all depot commands related to container builds. To install the Depot CLI, see Installation.

Other Depot product CLI references:

• CLI overview and platform commands
• Depot CI commands
• Agents commands

Specifying a Depot project

Some commands need to know which project to route the build to.

For interactive terminals calling build or bake, if you don't specify a project, you will be prompted to choose a project when using an interactive prompt and given the option to save that project for future use in a depot.json file.

Alternatively, you can specify the Depot project for any command using any of the following methods:

1. Use the --project flag with the ID of the project you want to use
2. Set the DEPOT_PROJECT_ID environment variable to the ID of the project you want to use

Authentication

The Depot CLI supports different authentication mechanisms based on where you're running your build, you can read more about them in our authentication docs.

Local builds with the CLI

For the CLI running locally, you can use the depot login command to authenticate with your Depot account, and the depot logout command to log out. This will generate a user token and store it on your local machine. We recommended only using this option when running builds locally.

Build with the CLI in a CI environment

When using the CLI in a CI environment like GitHub Actions, we recommend configuring your workflows to leverage our OIDC trust relationships. These prevent the need to store user tokens in your CI environment and allow you to authenticate with Depot using your CI provider's identity.

For CI providers that don't support OIDC, we recommended configuring your CI environment to use a project token.

The --token flag

Many Depot CLI commands accept a --token flag. The supported token types depend on the command. If no token is specified, the CLI checks DEPOT_TOKEN before the token stored on your local machine. See token resolution for details.

depot projects get and depot projects update require an organization token, even when you run them locally. User tokens from depot login do not work for these commands.

depot bake

The bake command builds images from an HCL, JSON, or Docker Compose file. Each target defines an image to build, including its Dockerfile, platforms, tags, and build arguments.

By default, depot bake will leave the built image in the remote builder cache. If you want to download the image to your local Docker daemon (for instance, to docker run the result), use the --load flag. In some cases it is more efficient to load from the registry, so this may result in the build getting saved to the Depot Registry.

Alternatively, to push the image to a remote registry directly from the builder instance, use the --push flag.

Example

This docker-bake.hcl file defines two targets, app and db. A group lists targets to build together. The default group includes both targets:

group "default" {
  targets = ["app", "db"]
}

target "app" {
  dockerfile = "Dockerfile"
  platforms = ["linux/amd64", "linux/arm64"]
  tags = ["example/app:test"]
}

target "db" {
  dockerfile = "Dockerfile.db"
  platforms = ["linux/amd64", "linux/arm64"]
  tags = ["example/db:test"]
}

Without a target name, depot bake builds the targets in the default group:

depot bake -f docker-bake.hcl

To build only specific targets, include their names. For example:

depot bake -f docker-bake.hcl app

Use different Depot projects

To build each target with a different Depot project, set project_id in each target block. Replace <app-project-id> and <db-project-id> with your Depot project IDs:

group "default" {
  targets = ["app", "db"]
}

target "app" {
  dockerfile = "Dockerfile"
  platforms = ["linux/amd64", "linux/arm64"]
  tags = ["example/app:test"]
  project_id = "<app-project-id>"
}

target "db" {
  dockerfile = "Dockerfile.db"
  platforms = ["linux/amd64", "linux/arm64"]
  tags = ["example/db:test"]
  project_id = "<db-project-id>"
}

Save images to Depot Registry

Use the --save flag to store the built image in Depot Registry for later use. For example:

depot bake -f docker-bake.hcl app --save

Depot saves the image in Depot Registry with a <build-id>-<target-name> tag.

To add a custom tag, use the --save-tag flag. For example:

depot bake -f docker-bake.hcl app --save --save-tag v1.0.0

Depot appends the target name to the prefix you provide (<custom-tag>-<target-name>) and saves the image in Depot Registry. For the preceding example, the tag would be v1.0.0-app.

To save the image in Depot Registry and also push its configured tags, use the --push flag. You need to authenticate to the destination registry before running the command. This example pushes example/app:test to Docker Hub:

depot bake -f docker-bake.hcl app --save --push

To build and save every target in the default group, run the command without a target name. For example:

depot bake -f docker-bake.hcl --save

For the preceding example, Depot builds app and db and saves their images with <build-id>-app and <build-id>-db tags.

For details about configured tags and output settings, see Using the Depot Registry with bake.

Docker Compose support

Depot supports using bake to build Docker Compose files.

To use depot bake with a Docker Compose file, you can specify the file with the -f flag:

depot bake -f docker-compose.yml

Compose files have special extensions prefixed with x- to give additional information to the build process.

In this example, the x-bake extension is used to specify the tags for each service and the x-depot extension is used to specify different project IDs for each.

services:
  mydb:
    build:
      dockerfile: ./Dockerfile.db
      x-bake:
        tags:
          - ghcr.io/myorg/mydb:latest
          - ghcr.io/myorg/mydb:v1.0.0
      x-depot:
        project-id: 1234567890
  myapp:
    build:
      dockerfile: ./Dockerfile.app
      x-bake:
        tags:
          - ghcr.io/myorg/myapp:latest
          - ghcr.io/myorg/myapp:v1.0.0
      x-depot:
        project-id: 9876543210

Flags for bake

This command accepts all the command line flags as Docker's docker buildx bake command.

depot build

Runs a Docker build using Depot's remote builder infrastructure.

By default, depot build will leave the built image in the remote builder cache. If you would like to download the image to your local Docker daemon (for instance, to docker run the result), you can use the --load flag. In some cases it is more efficient to load from the registry, so this may result in the build getting saved to the Depot Registry.

Alternatively, to push the image to a remote registry directly from the builder instance, you can use the --push flag.

Example

# Build remotely
depot build -t repo/image:tag .

# Build remotely, download the container locally
depot build -t repo/image:tag . --load

# Lint your dockerfile
depot build -t repo/image:tag . --lint

# Build remotely, push to a registry
depot build -t repo/image:tag . --push

Flags for build

This command accepts all the command line flags as Docker's docker buildx build command.

depot cache

Interact with the cache associated with a Depot project. The cache command consists of subcommands for each operation.

depot cache reset

Reset the cache of the Depot project to force a new empty cache volume to be created.

Example

Reset the cache of the current project ID in the root depot.json

depot cache reset .

Reset the cache of a specific project ID

depot cache reset --project 12345678910

depot cargo

Run any Cargo command with Depot Cache configured as the remote sccache backend. Install sccache and authenticate with depot login before using this command.

All arguments other than --org are passed directly to Cargo:

depot cargo build --release
depot cargo test --workspace

If you belong to multiple organizations, select the cache namespace with --org:

depot cargo --org <organization-id> build --release

depot configure-docker

Configure Docker to use Depot's remote builder infrastructure. This command installs Depot as a Docker CLI plugin (i.e., docker depot ...), sets the Depot plugin as the default Docker builder (i.e., docker build), and activates a buildx driver (i.e. docker buildx buildx ...).

depot configure-docker

If you want to uninstall the plugin, you can specify the --uninstall flag.

depot configure-docker --uninstall

depot gocache

Configure Go tools to use Depot Cache. The Go tools will use the remote cache service to store and retrieve build artifacts.

Note: This requires Go 1.24 or later.

Set the environment variable GOCACHEPROG to depot gocache to configure Go to use Depot Cache.

export GOCACHEPROG='depot gocache'

Next, run your Go build commands as usual.

go build ./...

To set verbose output, add the --verbose option:

export GOCACHEPROG='depot gocache --verbose'

To clean the cache, you can use the typical go clean workflow:

go clean -cache

If you are in multiple Depot organizations and want to specify the organization, you can use the --organization flag.

export GOCACHEPROG='depot gocache --organization ORG_ID'

depot init

Initialize an existing Depot project in the current directory. The CLI will display an interactive list of your Depot projects for you to choose from, then write a depot.json file in the current directory with the contents {"id": "PROJECT_ID"}.

Example

depot init

depot list

Interact with Depot builds.

depot list builds

Display the latest Depot builds for a project. By default the command runs an interactive listing of depot builds showing status and build duration.

To exit type q or ctrl+c

Example

List builds for the project in the current directory.

depot list builds

Example

List builds for a specific project ID

depot list builds --project 12345678910

Example

The list command can output build information to stdout with the --output option. It supports json and csv.

Output builds in JSON for the project in the current directory.

depot list builds --output json

depot projects create

Create a new project in your Depot organization.

depot projects create "your-project-name"

Projects will be created with the default region us-east-1 and cache storage policy of 50 GB per architecture. You can specify a different region and cache storage policy using the --region and --cache-storage-policy flags.

depot projects create --region eu-central-1 --cache-storage-policy 100 "your-project-name"

If you are in more than one organization, you can specify the ID of the organization you want the project to be created in using the --organization flag.

depot projects create --organization <org-id> "your-project-name"

Flags for create

Additional flags that can be used with this command.

depot projects delete

Delete a project from your Depot organization. This permanently removes the project and all associated build data.

Note: Only organization admins can delete projects.

Example

depot projects delete

You can also use the --project-id flag to specify the project ID:

depot projects delete --project-id <project-id>

Flags for delete

Additional flags that can be used with this command.

depot projects get

Display the details and configuration of a Depot project.

This command requires an organization token. User tokens from depot login do not work. Create one in Organization Settings > API Tokens and pass it with --token or set DEPOT_TOKEN.

If no project ID is provided, the command uses DEPOT_PROJECT_ID or the project configured in depot.json in the current directory.

Example

depot projects get --token <organization-token>

You can pass a project ID as an argument, and use --output json for machine-readable output:

depot projects get <project-id> --output json --token <organization-token>

Flags for get

Additional flags that can be used with this command.

depot projects list

Display an interactive listing of current Depot projects. Selecting a specific project will display the latest builds. To return from the latest builds to projects, press ESC.

To exit type q or ctrl+c

Example

depot projects list

depot projects update

Update the name, region, or cache storage policy of a Depot project. Only the values you pass as flags are changed, and at least one of --name, --region, or --cache-storage-policy is required.

This command requires an organization token. User tokens from depot login do not work. Create one in Organization Settings > API Tokens and pass it with --token or set DEPOT_TOKEN.

If no project ID is provided, the command uses DEPOT_PROJECT_ID or the project configured in depot.json in the current directory.

Example

depot projects update --name "New project name" --token <organization-token>

You can pass a project ID as an argument, and use --output json for machine-readable output:

depot projects update <project-id> --region eu-central-1 --output json --token <organization-token>

Flags for update

Additional flags that can be used with this command.

depot image list

List images saved in a project's Depot Registry. In a terminal, the command opens an interactive table. When output is redirected, it defaults to CSV.

depot image list --project <project-id>
depot image list --project <project-id> --output json

depot image rm

Delete one or more images from the Depot Registry by tag. The aliases remove and delete are also available.

depot image rm --project <project-id> app:old app:staging

depot pull

Pull an image from the Depot Registry by build ID in a project.

Example

depot pull --project <project-id> <build-id>

You can also specify the tag to assign to the image using the -t flag.

Example

depot pull --project <project-id> -t <image-name>:<tag> <build-id>

There is also the option to pull an image for a specific platform.

depot pull --project <project-id> --platform linux/arm64 <build-id>

Flags for pull

Additional flags that can be used with this command.

depot pull-token

Generate a short-lived token (valid for 1 hour) to pull an image from the Depot Registry.

Example

depot pull-token --project <project-id>

You can also specify a build ID to generate a token for a specific build.

Example

depot pull-token --project <project-id> <build-id>

Flags for pull-token

Additional flags that can be used with this command.

depot push

Push an image from the Depot Registry to another registry. It uses registry credentials stored in Docker when pushing to registries. If you have not already authenticated with your registry, you should do so with docker login before running depot push.

Alternatively, you can specify the environment variables DEPOT_PUSH_REGISTRY_USERNAME and DEPOT_PUSH_REGISTRY_PASSWORD for the registry credentials. This allows you to skip the docker login step.

Example

depot push --project <project-id> <build-id>

You can also specify the tag to assign to the image that is being pushed by using the -t flag.

Example

depot push --project <project-id> -t <image-name>:<tag> <build-id>

Flags for push

Additional flags that can be used with this command.