# CLI

Reference for all `depot` commands related to container builds. To install the Depot CLI, see [Installation](/content/docs/cli/installation/index.html).

Other Depot product CLI references:

- [CLI overview and platform commands](/content/docs/cli/reference/overview/index.html)
- [Depot CI commands](/content/docs/cli/reference/depot-ci/index.html)
- [Agents commands](/content/docs/cli/reference/agents/index.html)

## Specifying a Depot project

Some commands need to know which [project](/content/docs/container-builds/overview#projects/index.html) to route the build to.

For interactive terminals calling [`build`](/content/docs/cli/reference/container-builds#depot-build/index.html) or [`bake`](/content/docs/cli/reference/container-builds#depot-bake/index.html), 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](/content/docs/cli/authentication/index.html).

### 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](/content/docs/cli/authentication#user-access-tokens/index.html) 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](/content/docs/cli/authentication#oidc-trust-relationships/index.html). 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](/content/docs/cli/authentication#project-tokens/index.html).

### The `--token` flag

Many Depot CLI commands accept a `--token` flag. The supported token types depend on the command. If no token is specified, the CLI checks `DEPOT_TOKEN` before the token stored on your local machine. See [token resolution](/content/docs/cli/authentication#token-resolution/index.html) for details.

`depot projects get` and `depot projects update` require an [organization token](/content/docs/cli/authentication#organization-tokens/index.html), even when you run them locally. User tokens from `depot login` do not work for these commands.

## `depot bake`

The `bake` command builds images from an HCL, JSON, or Docker Compose file. Each target defines an image to build, including its Dockerfile, platforms, tags, and build arguments.

By default, `depot bake` will leave the built image in the remote builder cache. If you want to download the image to your local Docker daemon (for instance, to `docker run` the result), 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, use the `--push` flag.

**Example**

This `docker-bake.hcl` file defines two targets, `app` and `db`. A group lists targets to build together. The `default` group includes both targets:

```hcl
group "default" {
  targets = ["app", "db"]
}

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

Without a target name, `depot bake` builds the targets in the `default` group:

```bash
depot bake -f docker-bake.hcl
```

To build only specific targets, include their names. For example:

```bash
depot bake -f docker-bake.hcl app
```

### Use different Depot projects

To build each target with a different Depot project, set `project_id` in each target block. Replace `<app-project-id>` and `<db-project-id>` with your Depot project IDs:

```hcl
group "default" {
  targets = ["app", "db"]
}

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

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

### Save images to Depot Registry

Use the `--save` flag to store the built image in [Depot Registry](/content/docs/registry/overview/index.html) for later use. For example:

```bash
depot bake -f docker-bake.hcl app --save
```

Depot saves the image in Depot Registry with a `<build-id>-<target-name>` tag.

To add a custom tag, use the `--save-tag` flag. For example:

```bash
depot bake -f docker-bake.hcl app --save --save-tag v1.0.0
```

Depot appends the target name to the prefix you provide (`<custom-tag>-<target-name>`) and saves the image in Depot Registry. For the preceding example, the tag would be `v1.0.0-app`.

To save the image in Depot Registry and also push its configured tags, use the `--push` flag. You need to authenticate to the destination registry before running the command. This example pushes `example/app:test` to Docker Hub:

```bash
depot bake -f docker-bake.hcl app --save --push
```

To build and save every target in the `default` group, run the command without a target name. For example:

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

For the preceding example, Depot builds `app` and `db` and saves their images with `<build-id>-app` and `<build-id>-db` tags.

For details about configured tags and output settings, see [Using the Depot Registry with bake](/content/docs/container-builds/how-to-guides/docker-bake#using-the-depot-registry-with-bake/index.html).

### Docker Compose support

Depot supports using bake to build [Docker Compose](/content/blog/depot-with-docker-compose/index.html) files.

To use `depot bake` with a Docker Compose file, you can specify the file with the `-f` flag:

```bash
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](/content/docs/cli/authentication/index.html))                                 |

## `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**

```bash
# Build remotely
depot build -t repo/image:tag .
```

```bash
# Build remotely, download the container locally
depot build -t repo/image:tag . --load
```

```bash
# Lint your dockerfile
depot build -t repo/image:tag . --lint
```

```bash
# 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`

```bash
depot cache reset .
```

Reset the cache of a specific project ID

```bash
depot cache reset --project 12345678910
```

## `depot cargo`

Run any Cargo command with Depot Cache configured as the remote [`sccache`](https://github.com/mozilla/sccache) backend. Install `sccache` and authenticate with `depot login` before using this command.

All arguments other than `--org` are passed directly to Cargo:

```bash
depot cargo build --release
depot cargo test --workspace
```

If you belong to multiple organizations, select the cache namespace with `--org`:

```bash
depot cargo --org <organization-id> build --release
```

## `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**

```bash
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.

```bash
depot list builds
```

**Example**

List builds for a specific project ID

```bash
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.

```bash
depot list builds --output json
```

## `depot projects create`

Create a new project in your Depot organization.

```bash
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.

```bash
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.

```bash
depot projects create --organization <org-id> "your-project-name"
```

### Flags for `create`

Additional flags that can be used with this command.

| Name                          | Description                                                                |
|-------------------------------|----------------------------------------------------------------------------|
| `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)                    |
| `cache-policy-keep-days`      | Build cache retention in days (default 14; 0 means no limit)              |
| `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**

```bash
depot projects delete
```

You can also use the `--project-id` flag to specify the project ID:

```bash
depot projects delete --project-id <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 get`

Display the details and configuration of a Depot project.

This command requires an [organization token](/content/docs/cli/authentication#organization-tokens/index.html). User tokens from `depot login` do not work. Create one in **Organization Settings > API Tokens** and pass it with `--token` or set `DEPOT_TOKEN`.

If no project ID is provided, the command uses `DEPOT_PROJECT_ID` or the project configured in `depot.json` in the current directory.

**Example**

```bash
depot projects get --token <organization-token>
```

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

```bash
depot projects get <project-id> --output json --token <organization-token>
```

### Flags for `get`

Additional flags that can be used with this command.

| Name              | Description                                                  |
|-------------------|-------------------------------------------------------------|
| `project-id`      | Depot project ID                                           |
| `output`          | Output format (`json`)                                     |
| `token`           | Organization token (or set `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**

```bash
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**

```bash
depot projects update --name "New project name" --token <organization-token>
```

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

```bash
depot projects update <project-id> --region eu-central-1 --output json --token <organization-token>
```

### Flags for `update`

Additional flags that can be used with this command.

| Name                          | Description                                                        |
|-------------------------------|--------------------------------------------------------------------|
| `project-id`                 | Depot project ID                                                   |
| `name`                        | Project name                                                       |
| `region`                      | Build data storage region                                         |
| `cache-storage-policy`        | Build cache to keep per architecture in GB                       |
| `output`                      | Output format (`json`)                                           |
| `token`                       | Organization token (or set `DEPOT_TOKEN`)                        |

## `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.

```bash
depot image list --project <project-id>
depot image list --project <project-id> --output json
```

| Name                     | Description                                         |
|--------------------------|-----------------------------------------------------|
| `output`                 | Non-interactive output format (`json` or `csv`)    |
| `project`                | Depot project ID                                    |
| `token`                  | Depot API token                                     |

## `depot image rm`

Delete one or more images from the Depot Registry by tag. The aliases `remove` and `delete` are also available.

```bash
depot image rm --project <project-id> app:old app:staging
```

| Name                     | Description                                         |
|--------------------------|-----------------------------------------------------|
| `project`                | Depot project ID                                    |
| `token`                  | Depot API token                                     |

## `depot pull`

Pull an image from the Depot Registry by build ID in a project.

**Example**

```bash
depot pull --project <project-id> <build-id>
```

You can also specify the tag to assign to the image using the `-t` flag.

**Example**

```bash
depot pull --project <project-id> -t <image-name>:<tag> <build-id>
```

There is also the option to pull an image for a specific platform.

```bash
depot pull --project <project-id> --platform linux/arm64 <build-id>
```

### 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**

```bash
depot pull-token --project <project-id>
```

You can also specify a build ID to generate a token for a specific build.

**Example**

```bash
depot pull-token --project <project-id> <build-id>
```

### 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**

```bash
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**

```bash
depot push --project <project-id> -t <image-name>:<tag> <build-id>
```

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

Ask AI