# Depot CLI: Overview and platform commands (https://depot.dev/docs/cli/reference/overview) The Depot CLI gives you command line access to Depot CI, container builds, and agent sandboxes. To install the Depot CLI, see [Installation](/docs/cli/installation). You can submit an issue or contribute to the Depot CLI in our public [GitHub repository](https://github.com/depot/cli). The following reference is for platform-wide Depot CLI commands. Other Depot product CLI references: * [Depot CI commands](/docs/cli/reference/depot-ci) * [Container builds commands](/docs/cli/reference/container-builds) * [Agents commands](/docs/cli/reference/agents) ## `depot login` Authenticates with your Depot account, automatically creating and storing a user token on your local machine. **Examples** ```shell # 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** ```shell 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** ```shell 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** ```shell depot org switch [org-id] ``` If you do not provide an `org-id`, you will be prompted to select one interactively. **Examples** ```shell # 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** ```shell depot org show ``` **Example** ```shell $ 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`](https://github.com/depot/test-report-action), the same data shown in the dashboard. To set up reporting, see [Depot CI test results](/docs/ci/observability/depot-ci-test-results) and [GitHub Actions test results](/docs/github-actions/observability/github-actions-test-results). `depot tests split`, `depot tests run`, and `depot tests report` are supported only in Depot CI and Depot GitHub Actions runner jobs. Depot CI authenticates automatically. For Depot GitHub Actions runners, grant the workflow `id-token: write` permission. 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** ```shell depot tests ``` **Examples** ```shell # List Depot CI results for one attempt $ depot tests # List Depot CI results for one job in a run $ depot tests --job test # List failed GitHub Actions results for one job $ depot tests --gha --status failed # Emit JSON for automation $ depot tests --output json ``` **Flags** | Flag | Description | | ---------------------- | -------------------------------------------------------------------------------------- | | `--ci` | Restrict the lookup to Depot CI test results (mutually exclusive with `--gha`) | | `--gha` | Restrict the lookup to GitHub Actions test results (mutually exclusive with `--ci`) | | `--job ` | Depot CI job key to select when the ID is a run | | `--workflow ` | Depot CI workflow path to filter jobs (for example `ci.yml`) | | `--status ` | Test status to include (unknown, passed, failed, errored, skipped); repeatable | | `--suite ` | Test suite name to include | | `--test ` | Test case name to include | | `--class ` | Test class name to include | | `--file ` | Source filename to include | | `--page-size ` | Number of results to return per page (max 500, default 100) | | `--page-token ` | Token to fetch the next page | | `--output ` | Output format: `auto`, `table`, or `json` (default `auto`) | | `--org ` | Specify a Depot organization ID (required if you belong to more than one organization) | | `--token ` | Depot API token | ### `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. ```shell 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](/docs/ci/how-to-guides/split-tests) 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** | Flag | Description | | -------------------------------- | ----------------------------------------------------------------------- | | `--index ` | Zero-based shard index; overrides the Depot CI matrix value. | | `--total ` | Total number of shards; overrides the Depot CI matrix value. | | `--candidate-type ` | Optional override for the runnable identity: `filename` or `classname`. | | `--timings-type ` | Timing granularity: `filename`, `classname`, or `testname`. | | `--candidates-command ` | Command that prints newline-delimited candidates. | | `--candidates-file ` | File containing newline-delimited candidates instead of standard input. | | `--key ` | Split-assignment key for distinct logical suites. | | `--output ` | Candidate output format: `text` (default) or `json`. | ### `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. ```shell 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`](https://github.com/depot/tests-run-action) example in [Split tests by timing](/docs/ci/how-to-guides/split-tests). `--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** | Flag | Description | | -------------------------------- | ---------------------------------------------------------------------------------------------- | | `--index ` | Zero-based shard index; overrides the Depot CI matrix value. | | `--total ` | Total number of shards; overrides the Depot CI matrix value. `1` runs all supplied candidates. | | `--candidate-type ` | Optional override for the runnable identity: `filename` or `classname`. | | `--timings-type ` | Timing granularity: `filename`, `classname`, or `testname`. | | `--candidates-command ` | Command that prints newline-delimited candidates. | | `--candidates-file ` | File containing newline-delimited candidates instead of standard input. | | `--split-key ` | Split-assignment key. Share it across shards of one logical test suite. | | `--report-key ` | Report upload key; set it only for multiple uploads in one job. | | `--command ` | Required shell command that receives selected candidates on standard input. | | `--report-path ` | Required JUnit XML path, directory, or glob; repeatable. | ### `depot tests report` Upload JUnit XML files that a test command has already created. This is the reporting-only counterpart to `depot tests run`. ```shell 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. ## 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.