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

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 recommend 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. 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:

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

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

Run Claude Code in remote agent sandboxes backed by Depot with automatic session & file system saving and resuming. Sessions are stored by Depot and can be resumed by session ID, allowing you to collaborate on any session in your organization across any environment.

By default, Claude Code runs in a remote sandbox environment.

Note: All flags not recognized by depot are passed directly through to the Claude CLI. This includes Claude flags like -p, --model, etc.

Example

Start a new Claude Code session with a custom ID:

depot claude --session-id feature-auth-redesign

Resume an existing session:

depot claude --resume feature-auth-redesign

Run Claude Code locally instead of in a sandbox:

Note: This will only persist the Claude Code session information up to Depot, but not execute in a remote sandbox.

depot claude --local --session-id local-development

Work with a Git repository in the sandbox:

depot claude --repository https://github.com/user/repo.git --branch main --session-id repo-work

Use a private repository with authentication:

Note: You can use the --git-secret flag to specify a secret containing your Git credentials, or use the Depot Code app installed in your GitHub organization.

depot claude secrets add GITHUB_TOKEN
depot claude --repository https://github.com/org/private-repo.git --git-secret GITHUB_TOKEN

Mix Depot flags with Claude flags:

depot claude --session-id older-claude-pr-9953 --model claude-3-opus-20240229 -p "write tests"

Use in a script with piped input:

cat code.py | depot claude -p "review this code" --session-id code-review

Flags for claude

depot claude list-sessions

List all saved Claude sessions for the organization. In interactive mode, pressing Enter on a session will start Claude with that session.

Example

List sessions interactively:

depot claude list-sessions

List sessions in JSON format:

depot claude list-sessions --output json

Flags for claude list-sessions

depot claude secrets

Manage secrets that can be used in Claude sandboxes. Secrets are stored securely and scoped to your organization, available as environment variables in sandbox sessions.

depot claude secrets add

Add a new secret to your organization. You'll be prompted to enter the secret value securely.

Example

# Add a secret interactively
depot claude secrets add GITHUB_TOKEN

# Add a secret with value (use with caution)
depot claude secrets add API_KEY --value "secret-value"

depot claude secrets list

List all secrets in your organization. Note that secret values are never displayed.

Example

depot claude secrets list

depot claude secrets remove

Remove a secret from your organization.

Example

depot claude secrets remove GITHUB_TOKEN

Flags for claude secrets

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.

export GOCACHEPROG='depot gocache'

Next, run your Go build commands as usual.

go build ./...

To set verbose output, add the --verbose option:

export GOCACHEPROG='depot gocache --verbose'

To clean the cache, you can use the typical go clean workflow:

go clean -cache

If you are in multiple Depot organizations and want to specify the organization, you can use the --organization flag.

export GOCACHEPROG='depot gocache --organization ORG_ID'

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.

Examples

# Login and select organization interactively
$ depot login

# Login and specify organization ID
$ depot login --org-id 1234567890

# Clear existing token before logging in
$ depot login --clear

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

depot projects delete

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

depot projects delete --project-id <project-id>

Flags for delete

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

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.

depot org

Manage organizations you have access to in Depot. The org command group provides tools to list, switch, and show your current organization context.

depot org list

List organizations that you can access. By default, this command opens an interactive table. You can also output the list in json or csv format for scripting.

Usage

depot org list

depot org switch

Set the current organization in your global Depot settings. This affects which organization is used by default for commands that support organization context.

Usage

depot org switch [org-id]

If you do not provide an org-id, you will be prompted to select one interactively.

Examples

# Switch to a specific organization by ID
$ depot org switch 1234567890

# Select organization interactively
$ depot org switch

depot org show

Show the current organization set in your global Depot settings.

Usage

depot org show

Example

$ depot org show
1234567890

FAQ

How can I minimize build output for CI or automated environments?

If you want cleaner, less verbose output from Depot builds (especially useful in CI pipelines or scripts), you can set the DEPOT_NO_SUMMARY_LINK environment variable to suppress various informational messages including:

• Build summary links and URLs
• New release update notifications
• Bake save/push instructions

Example:

export DEPOT_NO_SUMMARY_LINK=1
depot build .

You can also use the --progress=quiet flag on individual commands for minimal output:

depot build --progress=quiet .