Depot CLI

Official CLI for Depot - you can use the CLI to build Docker images via Depot's remote builder infrastructure.

---

⚡ Depot provides cloud-hosted container builder machines - our builders are quick, running on native hardware. Build caching is fully managed with no extra configuration.

More information →

---

• Depot CLI
  • Installation
  • Quick Start
  • Usage
    • depot bake
      • Flags for bake
    • depot build
      • Flags for build
    • depot cache
      • depot cache reset
    • depot exec
    • depot gocache
    • depot configure-docker
    • depot list
      • depot list projects
      • depot list builds
    • depot projects
      • depot projects create
      • depot projects delete
      • depot projects list
    • depot init
    • depot login
    • depot logout
    • depot org
      • depot org list
      • depot org show
      • depot org switch
    • depot pull
    • depot push
    • depot pull-token
    • depot version
  • Contributing
  • License

Installation

For Mac, you can install the CLI with Homebrew:

brew install depot/tap/depot

For Linux, you can install with our installation script:

# Install the latest version
curl -L https://depot.dev/install-cli.sh | sh

# Install a specific version
curl -L https://depot.dev/install-cli.sh | sh -s 2.17.0

To install with the Proto toolchain manager, run:

proto plugin add depot "https://raw.githubusercontent.com/depot/cli/refs/heads/main/proto.yaml
proto install depot

For all other platforms, you can download the binary directly from the latest release.

Quick Start

1. Run depot login to authenticate with your Depot account.
2. cd to your project directory.
3. Run depot init to link the local directory with a Depot project - this will create a depot.json file in the current directory.
4. Run depot build -t repo/image:tag .

Usage

depot bake

Run a Docker build from a HCL, JSON, or Compose file using Depot's remote builder infrastructure. This command accepts all the command line flags as Docker's docker buildx bake command, you can run depot bake --help for the full list.

The bake command needs to know which project id to route the build to. For passing the project id you have four options available to you:

1. Run depot init at the root of your repository and commit the resulting depot.json file
2. Use the --project flag in your depot bake command
3. Set the DEPOT_PROJECT_ID environment variable which will be automatically detected.
4. Use x-depot extension field in your docker-compose.yml file.

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.

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

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 a specific target in the bake file, you can specify it in the bake command:

depot bake -f docker-bake.hcl original

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

| Name | Description | | ---------------- | --------------------------------------------------------------------------------------------------------- | | build-platform | Run builds on this platform ("dynamic", "linux/amd64", "linux/arm64") (default "dynamic") | | file | Build definition file | | help | Show the help doc for bake | | lint | Lint Dockerfiles of targets before the build | | lint-fail-on | Set the lint severity that fails the build ("info", "warn", "error", "none") (default "error") | | load | Shorthand for "--set=*.output=type=docker" | | metadata-file | Write build result metadata to the file | | no-cache | Do not use cache when building the image | | print | Print the options without building | | progress | Set type of progress output ("auto", "plain", "tty"). Use plain to show container output (default "auto") | | project | Depot project ID | | provenance | Shorthand for "--set=*.attest=type=provenance" | | pull | Always attempt to pull all referenced images | | push | Shorthand for "--set=*.output=type=registry" | | save | Saves bake targets to the Depot registry | | sbom | Shorthand for "--set=*.attest=type=sbom" | | set | Override target value (e.g., "targetpattern.key=value") | | token | Depot API token |

depot build

Runs a Docker build using Depot's remote builder infrastructure. This command accepts all the command line flags as Docker's docker buildx build command, you can run depot build --help for the full list.

The build command needs to know which project id to route the build to. For passing the project id you have three options available to you:

1. Run depot init at the root of your repository and commit the resulting depot.json file
2. Use the --project flag in your depot build command
3. Set the DEPOT_PROJECT_ID environment variable which will be automatically detected

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

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

Flags for build

| Name | Description | | ----------------- | -------------------------------------------------------------------------------------------