gem-hunter

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 build cancel
    • depot cache
      • depot cache reset
    • depot checks
    • depot exec
    • depot gocache
    • depot configure-docker
    • depot jobs
      • depot jobs metrics
      • depot jobs analytics
    • depot list
      • depot list projects
      • depot list builds
      • depot list jobs
    • depot projects
      • depot projects create
      • depot projects delete
      • depot projects list
    • depot init
    • depot login
    • depot logout
    • depot org
      • depot org credits
      • depot org list
      • depot org show
      • depot org switch
    • depot pull
    • depot push
    • depot pull-token
    • depot version
  • Contributing
  • License

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.

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 .

Set DEPOT_IN_AUTOMATION=1 to suppress build summary URLs, saved-image pull/push hints, and new-version notifications in scripts and CI. Any non-empty value enables this behavior; build progress and errors are still printed.

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

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

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

Request cancellation of container builds using an organization API token supplied through DEPOT_TOKEN or --token.

depot build cancel <build-id> [<build-id>...]
depot build cancel --project <project-id> --all-running --dry-run
depot build cancel --project <project-id> --all-running --yes --output json

Cancellation is asynchronous. Finished builds are successful no-ops; failures are reported per build and cause a nonzero exit status. Bulk cancellation selects all running builds before requesting confirmation; use --yes for scripts.

See build cancellation for authentication, selection, and output details. To build a directory named cancel, use depot build ./cancel.

Interact with the cache associated with a Depot project. The cache command consists of subcommands for each operation.

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

Manage Agent Checks and saved review agents. Requires Agent Checks access in the selected organization.

depot checks list --repo github:depot/api --outcome rejected
depot checks get <check-id-or-attempt-id>
depot checks attempts <check-id-or-attempt-id> -n 100 --output json
depot checks run <agent-id> --repo github:depot/api --ref feature
depot checks retry <check-id-or-attempt-id>
depot checks transcript <check-id-or-attempt-id> --output json --output-file transcript.jsonl
depot checks resolve <check-id-or-attempt-id> --finding 0
depot checks unresolve <check-id-or-attempt-id> --all

depot checks agents list
depot checks agents get <agent-id>
depot checks agents create --name Security --instructions-file review.md --repo github:depot/api
depot checks agents update <agent-id> --model default
depot checks agents models

A check ID selects its latest attempt; an attempt ID selects that execution. Results include both IDs, revision, state, outcome, summary, findings with original zero-based indexes, resolutions, and available execution details. JSON follows CI's snake_case convention: run/retry return check_id and attempt_id; get returns the selected attempt directly. Check lists return arrays of {check_id, created_at, current_attempt}; history returns an array of attempts. Resolve/unresolve return {check_id, created_at, current_attempt}. Each attempt includes structured result when its stored JSON is valid, plus the original result_json string when present. Agent reads/saves return the configuration directly (agent_id, name, instructions, model_id, repos, events); agent lists return an array of configurations. Models output includes default_model_id and models. Transcript --output json emits the exact JSONL archive; --output jsonl is an equivalent alias.

List tables shorten long display names, repositories and branches, and show 12-character head SHAs. IDs remain complete; get and JSON retain full values. Transcript file exports confirm the destination and saved byte count on stderr after the file is saved successfully. API errors include the failed operation while preserving the underlying error status.

list supports --agent, --repo, --forge, --branch (requires --repo), --sha (head or base prefix), --outcome, and --query (agent name, repository, branch, or SHA prefix). Outcomes are running (including queued), done, passed, findings (a passing review with advice), rejected, resolved, and failed (execution failure). checks list, checks agents list, and checks attempts use -n as a positive total result limit (default 50), matching CI run listing. The CLI follows API pages internally until that limit is reached or there are no more matches; no --all or --page-token is exposed.

checks list --repo owner/repo matches that full name across forges. Add --forge github, --forge origin, or --forge depot to narrow the results, or use --forge alone to list checks from that forge. cursor-origin and code remain accepted aliases for origin and depot. Qualified repository selectors also work: github:owner/repo, origin:owner/repo, or depot:name (including the legacy cursor-origin:owner/repo and code:name). If --forge is also supplied, the forges must agree. run and agent create/update still require a qualified repository selector. run accepts --ref with an optional full --commit-sha, or --head, plus an optional --base for either mode. By default it reviews the default branch's HEAD against its first parent (or the empty tree for an initial commit). One-off runs do not change the agent's watched repositories. retry reuses the captured configuration and revisions, creates a new attempt under the same check, and only accepts checks whose current execution failed. An explicitly selected historical attempt cannot be retried or have its findings changed.

Agent create/update supports --name, --instructions or --instructions-file (- reads stdin), --model, repeatable --repo, and repeatable --event (for example github:opened, github:synchronize, or code:push). Omitted update fields are preserved; supplied repositories/events replace that selection. Use --clear-repos to remove all watches, --clear-events to disable automatic checks, and --model default to follow the current default model. Creation defaults to no watched repositories and the supported events except github:push.

Commands support --org, --token (or DEPOT_TOKEN), and --output json. Transcript output is readable text by default; --output jsonl preserves the original archived bytes. Archives are verified against their size and SHA-256 before output and are subject to availability and retention. There is no live transcript following or waiting option. Run/retry return both IDs immediately. Exit 0 means the operation succeeded, including inspecting failed/rejected checks; exit 1 means input, authentication/API, download, or output failure. Review outcomes are reported in the output.

Execute a command with an injected BuildKit connection. This command launches a remote machine in Depot's infrastructure, establishes a connection to it, and makes this connection available to the specified command through an environment variable.

Example

# Run a command with access to a remote BuildKit instance
depot exec --platform linux/amd64 docker build .

# Run a Dagger command using Depot's infrastructure
depot exec dagger run ...

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

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

List GitHub Actions jobs run on Depot, newest first, or inspect one job by its GitHub job ID. This command is for Depot GitHub Actions runners; use depot ci for Depot CI executions.

depot jobs --repo acme/api --status finished --conclusion failure
depot jobs 123456789 --repo acme/api --output json

Listings include job and workflow names, status, conclusion, runner label, execution duration, and queue time. Individual job details also include lifecycle timestamps, billable time, requested CPU and memory, and the GitHub URL. Requested resources describe runner capacity, not measured utilization. The API does not currently expose step timing breakdowns.

Use --org to select an organization (otherwise the current organization is used). Authentication uses --token, DEPOT_TOKEN, or saved Depot credentials. Output defaults to a readable table in a terminal and JSON when piped. Explicit --output json never prompts for login. JSON follows the API's protobuf JSON format: field names use camelCase, enums use symbolic names, and 64-bit integers are strings to preserve precision.

Filter listings with repeatable --repo, --status, --conclusion, and --runner-label flags. Use --query to search job/workflow names or exact numeric job/run IDs. A single-job lookup requires exactly one --repo; listing filters do not apply to it.

Fetch CPU and memory utilization for one GitHub Actions job execution using its GitHub job ID and exactly one --repo owner/name. Use depot jobs --repo owner/name to find job IDs. Completed jobs return their execution metrics; running jobs return a snapshot that can grow on subsequent requests.

depot jobs metrics 123456789 --repo acme/api
depot jobs metrics 123456789 --repo acme/api --org org_123 --output json

Uses the same authentication, organization selection, and --output auto|table|json behavior as depot jobs. Tables show job/runner context, snapshot time, availability and reason, observed timestamps, average/peak CPU and memory utilization, sample counts, and downsampling details. JSON includes the full API response with job, availability, stats, cap, samples, and snapshotAt. Samples are ordered by timestamp. CPU measures user-mode utilization averaged across cores; memory measures used memory as a fraction of total memory. Utilization is a fraction from 0 to 1 in JSON and a percentage in tables.

Unavailable measurements are omitted from JSON's optional utilization fields and displayed as n/a in table summaries; measured zero remains zero. availability distinguishes available, partial, and unavailable telemetry and includes the API's reason. Availability describes the observed samples and does not guarantee coverage of the entire execution. Telemetry-store errors fail the command instead of returning an empty success response.

The API limits execution windows to seven days and returns at most 5,000 samples. When samples are downsampled, cap reports the raw/returned counts, limit, and strategy. The evenly_spaced strategy retains the first and last samples but may omit intermediate peaks. Summary statistics are calculated by the API across all observed per-second samples before downsampling. This command has no time-range or pagination flags and does not expose per-step measurements.

Show aggregate CPU and memory utilization (average and peak), average and p95 job duration, and failure rate by repository, workflow, and job. Groups are ordered by descending job count. These are metrics across job executions, not resource measurements for an individual job or step. Analytics may lag completed jobs by up to 15 minutes; dataThrough identifies data freshness.

depot jobs analytics --repo acme/api --job test --output json
depot jobs analytics --start 2026-10-01T00:00:00Z --end 2026-10-08T00:00:00Z

Filter with repeatable --repo, --workflow (display name), --workflow-path, --job (workflow job key), and --runner-label flags. Table utilization and failure rates are percentages; JSON retains the API's fractions from 0 to 1. Durations are in seconds.

Both listings and analytics default to the last 30 days. For an explicit time window, supply both --start (inclusive) and --end (exclusive) as RFC 3339 timestamps, at most 90 days apart. They return one page, with --page-size from 1 to 250 (default 50). To continue, pass the response's nextPageToken as --page-token, keeping all filters and the time range unchanged. Tables print the continuation token when another page is available.

Interact with Depot projects, builds, and GitHub Actions jobs.

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

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

List GitHub Actions jobs using the same flags and output as depot jobs without a job ID.

depot list jobs --repo acme/api --output json

Create and manage Depot projects.

Create a new Depot project. This command creates a new project in your Depot account with the specified configuration.

Use --max-concurrent-builds to set the number of concurrent builds per builder instance before horizontal autoscaling adds another instance. Accepts integers from 1 to 2147483647; omitting it disables autoscaling for a new project. This is a per-instance threshold, not a project-wide build limit.

Example

# Create a project with default settings
depot projects create your-project-name

# Create a project with custom settings
depot projects create --organization your-org-id --region us-west-2 --cache-storage-policy 100 --cache-policy-keep-days 30 your-project-name

# Allow up to three concurrent builds per builder instance
depot projects create your-project-name --max-concurrent-builds 3

View a Depot project's details and configuration. Pass a project ID as an argument or with --project-id. If neither is provided, the command uses DEPOT_PROJECT_ID or the project configured in depot.json.

Text output includes Builds per instance, or Disabled when autoscaling is disabled. Project create, get, and update JSON output includes max_concurrent_builds as a number, or null when autoscaling is disabled.

Example

# View the project configured in the current directory
depot projects get

# View a specific project as JSON
depot projects get your-project-id --output json

Update a Depot project's name, region, cache storage policy, or autoscaling. Only values passed as flags are changed. Pass a project ID as an argument or with --project-id. If neither is provided, the command uses DEPOT_PROJECT_ID or the project configured in depot.json.

Set --max-concurrent-builds to a positive integer to enable or change autoscaling, or use --disable-autoscaling to remove the threshold. These flags are mutually exclusive. Omitting both preserves the existing autoscaling setting.

Example

# Rename the project configured in the current directory
depot projects update --name "New project name"

# Update a specific project's region and cache storage policy
depot projects update your-project-id --region eu-central-1 --cache-storage-policy 100

# Set the autoscaling threshold to three builds per builder instance
depot projects update your-project-id --max-concurrent-builds 3

# Disable project autoscaling
depot projects update your-project-id --disable-autoscaling

Delete a Depot project. If no project ID is specified, the command will display an interactive list of projects to choose from.

Example

# Delete a specific project
depot projects delete --project-id your-project-id

# Delete a project interactively
depot projects delete

# Delete a project without confirmation prompt
depot projects delete --project-id your-project-id --yes

List Depot projects. This command is functionally identical to depot list projects and provides an interactive listing of your Depot projects.

Example

depot projects list

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

Authenticates with your Depot account, automatically creating and storing a personal API token on your local machine.

Example

depot login

Remove any saved login details from your local machine.

Example

depot logout

Manage Depot organizations. The org command consists of subcommands for each operation.

Show the organization's remaining posted Stripe invoice credits. This is the same balance shown on the billing page; unbilled usage and upcoming invoices are not deducted, and free-trial allowances and included plan minutes are excluded.

Use an organization API token or a read-only organization token through DEPOT_TOKEN, --token, or the CLI configuration. A user token from depot login is not supported by this endpoint. The token determines the organization, so depot org switch does not change which balance is read and there is no --org flag. The command never prompts for login.

# With DEPOT_TOKEN set to an organization token:
depot org credits
depot org credits --output json

Default output uses the currency's decimal places without rounding the balance:

Remaining credits: USD 125.00
Observed at: 2026-10-27T12:00:00Z

JSON output preserves the API's exact minor-unit amount as a string, including "0" when credit is exhausted:

{
  "remainingCreditMinor": "12500",
  "currency": "USD",
  "observedAt": "2026-10-27T12:00:00Z"
}

For USD, 12500 means $125.00. The timestamp records when the provider balance was read, not when usage was last processed.

Each invocation reads the API once. Reads are limited to one per organization per minute across all tokens and ten per ten seconds across the API fleet. Excess polls exit with an error containing the server's retry delay. The command does not retry automatically or cache balances. Poll hourly for most credit alerts, and handle failed commands separately from a successful zero balance.

Display an interactive listing of organizations that you can access. The command shows organization IDs and names in a table format.

To exit type q or ctrl+c

Example

depot org list

Example

The list command can output organization information to stdout with the --output option. It supports json and csv.

Output organizations in JSON format:

depot org list --output json

Output organizations in CSV format:

depot org list --output csv

Show the current organization ID that is set in your global Depot settings.

Example

depot org show

Set the current organization in global Depot settings. You can either specify an organization ID as an argument or run the command interactively to select from available organizations.

Example

Switch to a specific organization by ID:

depot org switch your-org-id

Example

Switch to an organization interactively:

depot org switch

Pull an image from the Depot registry to your local Doc