CLI Reference

Below is a reference to the depot CLI, including all config, commands, flags, and options. To submit an issue or features please see our CLI repo over on GitHub.

Specifying a Depot project

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

For interactive terminals calling build or bake, if 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 recommended 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.

Commands

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.

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 ephemeral 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.

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 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 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 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 login

Authenticates with your Depot account, automatically creating and storing a user token on your local machine.

Example

depot login

depot logout

Logout out of your Depot account, removing your user token from your local machine.

Example

depot logout

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 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 list projects

depot pull

Pull an image from the ephemeral 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 to pull an image from the ephemeral 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 ephemeral registry to a remote 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.

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.