Awesome
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.
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
For all other platforms, you can download the binary directly from the latest release.
Quick Start
- Run
depot login
to authenticate with your Depot account. cd
to your project directory.- Run
depot init
to link the local directory with a Depot project - this will create adepot.json
file in the current directory. - 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:
- Run
depot init
at the root of your repository and commit the resultingdepot.json
file - Use the
--project
flag in yourdepot bake
command - Set the
DEPOT_PROJECT_ID
environment variable which will be automatically detected. - Use
x-depot
extension field in yourdocker-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 ephemeral 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:
- Run
depot init
at the root of your repository and commit the resultingdepot.json
file - Use the
--project
flag in yourdepot build
command - 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 |
---|---|
add-host | Add a custom host-to-IP mapping (format: "host:ip") |
allow | Allow extra privileged entitlement (e.g., "network.host", "security.insecure") |
attest | Attestation parameters (format: "type=sbom,generator=image") |
build-arg | Set build-time variables |
build-context | Additional build contexts (e.g., name=path) |
build-platform | Run builds on this platform ("dynamic", "linux/amd64", "linux/arm64") (default "dynamic") |
cache-from | External cache sources (e.g., "user/app:cache", "type=local,src=path/to/dir") |
cache-to | Cache export destinations (e.g., "user/app:cache", "type=local,dest=path/to/dir") |
cgroup-parent | Optional parent cgroup for the container |
file | Name of the Dockerfile (default: "PATH/Dockerfile") |
help | Show help doc for build |
iidfile | Write the image ID to the file |
label | Set metadata for an image |
lint | Lint Dockerfile before the build |
lint-fail-on | Set the lint severity that fails the build ("info", "warn", "error", "none") (default "error") |
load | Shorthand for "--output=type=docker" |
metadata-file | Write build result metadata to the file |
network | Set the networking mode for the "RUN" instructions during build (default "default") |
no-cache | Do not use cache when building the image |
no-cache-filter | Do not cache specified stages |
output | Output destination (format: "type=local,dest=path") |
platform | Set target platform for build |
progress | Set type of progress output ("auto", "plain", "tty"). Use plain to show container output (default "auto") |
project | Depot project ID |
provenance | Shortand for "--attest=type=provenance" |
pull | Always attempt to pull all referenced images |
push | Shorthand for "--output=type=registry" |
quiet | Suppress the build output and print image ID on success |
save | Saves build to the Depot ephemeral registry |
sbom | Shorthand for "--attest=type=sbom" |
secret | Secret to expose to the build (format: "id=mysecret[,src=/local/secret]") |
shm-size | Size of "/dev/shm" |
ssh | SSH agent socket or keys to expose to the build |
tag | Name and optionally a tag (format: "name:tag") |
target | Set the target build stage to build |
token | Depot API token |
ulimit | Ulimit options (default []) |
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 ...
) and sets the Depot plugin as the default Docker builder (i.e., docker build
).
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 projects and builds.
depot list projects
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 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 {"projectID": "xxxxxxxxxx"}
.
Example
depot init
depot login
Authenticates with your Depot account, automatically creating and storing a personal API token on your local machine.
Example
depot login
depot logout
Remove any saved login defails from your local machine.
Example
depot logout
depot pull
Pull an image from the Depot ephemeral registry to your local Docker daemon.
depot pull --tag repo:tag <BUILD_ID>
Pull all bake images from the Depot ephemeral registry to your local Docker daemon. By default images will be tagged with the bake target names.
depot pull <BUILD_ID>
depot push
Push an image from the Depot ephemeral registry to a destination registry.
depot push --tag repo:tag <BUILD_ID>
Contributing
PR contributions are welcome! The CLI codebase is evolving rapidly, but we are happy to work with you on your contribution.
License
MIT License, see LICENSE