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

A variety of Depot CLI calls accept a --token flag, which allows you to specify a user or project token to use for the command. If no token is specified, the CLI will attempt to use the token stored on your local machine or look for an environment variable called DEPOT_TOKEN.

depot bake

The bake command allows you to define all of your build targets in a central file, either HCL, JSON, or Compose. You can then pass that file to the bake command and Depot will build all of the target images with all of their options (i.e. platforms, tags, build arguments, etc.).

By default, depot bake 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

An example docker-bake.hcl file:

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

target "original" {
  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"]
}

To build all of the images we just need to call bake:

depot bake -f docker-bake.hcl

If you want to build different targets in the bake file with different Depot projects, you can specify the project_id in the target block:

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

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

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

If you want to build a specific target in the bake file, you can specify it in the bake command:

depot bake -f docker-bake.hcl original

You can also save all of the targets built in a bake or compose file to the Depot Registry for later use with the --save flag:

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

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 12345678910 "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.

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

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

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

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.

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"

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

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.