Depot CLI: Overview and platform commands

The Depot CLI gives you command line access to Depot CI, container builds, and agent sandboxes. To install the Depot CLI, see Installation.

You can submit an issue or contribute to the Depot CLI in our public GitHub repository.

The following reference is for platform-wide Depot CLI commands. Other Depot product CLI references:

• Depot CI commands
• Container builds commands
• Agents commands

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

depot tests

List parsed test results for a Depot CI or GitHub Actions job. Results come from the JUnit XML your jobs report with the depot/test-report-action, the same data shown in the dashboard. To set up reporting, see Depot CI test results and GitHub Actions test results.

By default, Depot uses the given ID to retrieve Depot CI results, then falls back to GitHub Actions. Pass --ci or --gha to restrict the lookup to one source.

For Depot CI, the ID may be a run, job, or attempt ID. A job ID resolves to its latest attempt, and an attempt ID points at one specific attempt. A run ID resolves to the latest attempt when the run has a single job: if the run has more than one job, narrow it with --job (and --workflow when the same job name appears in multiple workflows). For GitHub Actions, pass the GitHub Actions job ID with --gha. The command prints a table in a terminal and JSON when piped, so it drops straight into scripts.

Usage

depot tests <id>

Examples

# List Depot CI results for one attempt
$ depot tests <attempt-id>

# List Depot CI results for one job in a run
$ depot tests <run-id> --job test

# List failed GitHub Actions results for one job
$ depot tests <github-job-id> --gha --status failed

# Emit JSON for automation
$ depot tests <attempt-id> --output json

Flags

depot tests split

Print the candidates assigned to one timing-balanced test shard. Use --candidates-command to discover runnable candidates inline; standard input and --candidates-file remain supported alternatives. Use this lower-level command when your test runner needs direct control over how it receives candidates.

depot tests split \
  --candidates-command 'go list ./...' \
  --index 0 --total 4 \
  --timings-type testname

The command uses historical JUnit timings when available. Filename candidates without timing history fall back to file size; other candidates receive deterministic fallback weights until Depot has timing data. See Split tests by timing for a complete workflow example.

--candidate-type is optional. The CLI infers filename for recognized source or test-file paths and classname for other candidates. Set it when that apparent identity differs from the JUnit field used for timing lookup; for example, Vitest and Playwright accept file paths but write their timing identity to JUnit classname.

--timings-type controls timing granularity. It defaults to the resolved candidate identity and uses whole-candidate timings; set it to testname to calculate each candidate's duration from individual JUnit test cases rather than the reported duration of the whole filename or classname unit.

In Depot CI matrix jobs, omitted shard inputs use DEPOT_MATRIX_JOB_INDEX and DEPOT_MATRIX_JOB_TOTAL. Explicit flags override those values. The automatic values cover the immediate strategy's flattened matrix; use explicit values when only one matrix axis should split or when a reusable workflow needs a different split scope.

Flags

depot tests run

Select a test shard, run a command with that shard's candidates on standard input, and upload the JUnit XML reports it creates. The command preserves the test command's exit code, after attempting to upload reports even when tests fail. In Depot CI matrix jobs, omitted shard inputs use DEPOT_MATRIX_JOB_INDEX and DEPOT_MATRIX_JOB_TOTAL. Explicit flags override those values. Automatic values cover the immediate strategy's flattened matrix, so use explicit values when only one axis should split or when a reusable workflow needs a different split scope. Set --total 1 to run all supplied candidates, even inside a matrix. Candidates are optional only when the effective total is 1; then the command runs with empty standard input if no candidate source is supplied.

depot tests run \
  --candidates-command 'go list ./...' \
  --index 0 --total 4 \
  --timings-type testname \
  --command 'xargs gotestsum --junitfile reports/junit.xml --' \
  --report-path reports/junit.xml

Use --split-key only to separate logical test suites that would otherwise share a split scope. --report-key identifies a report upload; use a distinct value only when one job uploads more than one report. For GitHub Actions and Depot CI workflows, see the depot/tests-run-action example in Split tests by timing.

--timings-type controls timing granularity. It defaults to the resolved candidate identity and uses whole-candidate timings; set it to testname to calculate each candidate's duration from individual JUnit test cases rather than the reported duration of the whole filename or classname unit.

Flags

depot tests report

Upload JUnit XML files that a test command has already created. This is the reporting-only counterpart to depot tests run.

depot tests report reports/junit.xml --key unit-tests

Pass report paths as positional arguments or with repeatable --report-path. Use --key to identify an upload invocation when the same job reports multiple independent suites.