# Depot CLI: Container builds commands reference (https://depot.dev/docs/cli/reference/container-builds) Reference for all `depot` commands related to container builds. To install the Depot CLI, see [Installation](/docs/cli/installation). Other Depot product CLI references: * [CLI overview and platform commands](/docs/cli/reference/overview) * [Depot CI commands](/docs/cli/reference/depot-ci) * [Agents commands](/docs/cli/reference/agents) ## Specifying a Depot project Some commands need to know which [project](/docs/container-builds/overview#projects) to route the build to. For interactive terminals calling [`build`](#depot-build) or [`bake`](#depot-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](/docs/cli/authentication). ### 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](/docs/cli/authentication#user-access-tokens) 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](/docs/cli/authentication#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](/docs/cli/authentication#project-tokens). ### 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: ```hcl 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`: ```shell 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: ```hcl 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: ```shell 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](/docs/registry/overview) for later use with the `--save` flag: ```shell depot bake -f docker-bake.hcl --save ``` ### Docker Compose support Depot supports using bake to build [Docker Compose](/blog/depot-with-docker-compose) files. To use `depot bake` with a Docker Compose file, you can specify the file with the `-f` flag: ```shell 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. ```yaml 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. {/* */} | 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 the build to the Depot Registry | | `save-tag` | Saves the tag prepended to each target to the Depot Registry | | `sbom` | Shorthand for "--set=\*.attest=type=sbom" | | `sbom-dir` | Directory to store SBOM attestations | | `set` | Override target value (e.g., "targetpattern.key=value") | | `token` | Depot token ([authentication docs](/docs/cli/authentication)) | {/* */} ## `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** ```shell # Build remotely depot build -t repo/image:tag . ``` ```shell # Build remotely, download the container locally depot build -t repo/image:tag . --load ``` ```shell # Lint your dockerfile depot build -t repo/image:tag . --lint ``` ```shell # 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. {/* */} | 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` | Shorthand 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 the build to the Depot Registry | | `save-tag` | Saves the tag provided to the Depot Registry | | `sbom` | Shorthand for "--attest=type=sbom" | | `sbom-dir` | Directory to store SBOM attestations | | `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 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` ```shell depot cache reset . ``` Reset the cache of a specific project ID ```shell 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 ...`). ```shell depot configure-docker ``` If you want to uninstall the plugin, you can specify the `--uninstall` flag. ```shell 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. ```shell export GOCACHEPROG='depot gocache' ``` Next, run your Go build commands as usual. ```shell go build ./... ``` To set verbose output, add the --verbose option: ```shell export GOCACHEPROG='depot gocache --verbose' ``` To clean the cache, you can use the typical `go clean` workflow: ```shell go clean -cache ``` If you are in multiple Depot organizations and want to specify the organization, you can use the `--organization` flag. ```shell 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** ```shell 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. ```shell depot list builds ``` **Example** List builds for a specific project ID ```shell 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. ```shell depot list builds --output json ``` ## `depot projects create` Create a new project in your Depot organization. ```shell 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. ```shell 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. ```shell depot projects create ---organization 12345678910 "your-project-name" ``` ### Flags for `create` Additional flags that can be used with this command. {/* */} | Name | Description | | ---------------------- | -------------------------------------------------------------------- | | `platform` | Pulls image for specific platform ("linux/amd64", "linux/arm64") | | `organization` | Depot organization ID | | `region` | Build data will be stored in the chosen region (default "us-east-1") | | `cache-storage-policy` | Build cache to keep per architecture in GB (default 50) | | `token` | Depot token | {/* */} ## `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** ```shell depot projects delete ``` You can also use the `--project-id` flag to specify the project ID: ```shell depot projects delete --project-id ``` ### Flags for `delete` Additional flags that can be used with this command. {/* */} | Name | Description | | ------------ | ---------------------------------------------- | | `project-id` | Depot project ID | | `yes` | Confirm deletion, skip the confirmation prompt | | `token` | Depot token | {/* */} ## `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** ```shell depot list projects ``` ## `depot pull` Pull an image from the Depot Registry by build ID in a project. **Example** ```shell depot pull --project ``` You can also specify the tag to assign to the image using the `-t` flag. **Example** ```shell depot pull --project -t : ``` There is also the option to pull an image for a specific platform. ```shell depot pull --project --platform linux/arm64 ``` ### Flags for `pull` Additional flags that can be used with this command. {/* */} | Name | Description | | ---------- | ------------------------------------------------------------------------------ | | `platform` | Pulls image for specific platform ("linux/amd64", "linux/arm64") | | `progress` | Set type of progress output ("auto", "plain", "tty", "quiet") (default "auto") | | `project` | Depot project ID | | `tag` | Optional tags to apply to the image | | `token` | Depot token | {/* */} ## `depot pull-token` Generate a short-lived token (valid for 1 hour) to pull an image from the Depot Registry. **Example** ```shell depot pull-token --project ``` You can also specify a build ID to generate a token for a specific build. **Example** ```shell depot pull-token --project ``` ### Flags for `pull-token` Additional flags that can be used with this command. {/* */} | Name | Description | | --------- | ---------------- | | `project` | Depot project ID | | `token` | Depot token | {/* */} ## `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** ```shell depot push --project ``` You can also specify the tag to assign to the image that is being pushed by using the `-t` flag. **Example** ```shell depot push --project -t : ``` ### Flags for `push` Additional flags that can be used with this command. {/* */} | Name | Description | | ---------- | ------------------------------------------------------------------------------ | | `progress` | Set type of progress output ("auto", "plain", "tty", "quiet") (default "auto") | | `project` | Depot project ID | | `tag` | Optional tags to apply to the image | | `token` | Depot token | {/* */} ## For AI Agents The full site index is at [llms.txt](https://depot.dev/llms.txt). Append `.md` to any documentation, blog, changelog, or customer URL to fetch its markdown source directly.