> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trunk.io/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI Reference

> CLI tool for uploading test results to Trunk from CI, enabling flaky test detection and quarantining.

Trunk detects and tracks flaky tests in your repos by receiving uploads from your test runs in CI, uploaded by the Trunk Analytics CLI (`trunk-analytics-cli`). These uploads happen in the CI jobs used to run tests in your nightly CI, post-commit jobs, and PR checks.

You run the Trunk Analytics CLI through the [`trunk` CLI](https://docs.trunk.io/flaky-tests/get-started/trunk-cli): `trunk flakytests` (or `trunk ft`) downloads it, runs it with your arguments, and passes it the API key you stored with `trunk auth api-key set`. `trunk flakytests <command>` takes the same commands and options as `trunk-analytics-cli <command>`.

## Guides

If you're setting up Trunk Flaky Tests for the first time, you can follow the guides for your CI provider and test framework.

> [card] [Guides by Test Frameworks](https://docs.trunk.io/flaky-tests/get-started/frameworks/)

> [card] [Guides by CI Provider](https://docs.trunk.io/flaky-tests/get-started/ci-providers/)

## Install

Install the `trunk` CLI and store an API key with the **Upload test results** permission:

```bash theme={"system"}
curl -fsSL https://install.trunk.io | sh
TRUNK_ORG_API_KEY="$TRUNK_API_KEY" trunk auth api-key set
```

See [Trunk CLI](https://docs.trunk.io/flaky-tests/get-started/trunk-cli.md) for Windows, pinning versions, and running in CI.

## Running trunk-analytics-cli directly

You can download the Trunk Analytics CLI and run it yourself, without the `trunk` CLI. Pass it an API key with the **Upload test results** permission, with `--token` or the `TRUNK_API_TOKEN` environment variable. In the examples on this page, replace `trunk flakytests` with `./trunk-analytics-cli` and add `--token "$TRUNK_API_KEY"`.

> [!NOTE]
>
> The Trunk Analytics CLI 1.0.0 and later refuse the legacy organization token. To keep using it, pin a 0.17.x release by setting `VERSION` below.

### Manual Download

Releases are served from `https://trunk.io/releases/analytics-cli/prod`. `channel-1.json` there names the latest 1.x version (`{"latest": "x.y.z"}`), and each version's files live under `<version>/`. We provide executables for Linux and macOS. It’s a single file inside a tar and upon downloading the tar you will find a single binary - `trunk-analytics-cli` to use. To pin a version, set `VERSION` to it instead of reading `channel-1.json`.

> [!NOTE]
>
> Releases are also published on [GitHub](https://github.com/trunk-io/analytics-cli/releases), but GitHub rate-limits downloads, so it is not a reliable source for CI. Download from `trunk.io` instead.

```bash Linux (x64) theme={"system"}
SKU="trunk-analytics-cli-x86_64-unknown-linux.tar.gz"
VERSION=$(curl -fsSL --connect-timeout 10 --max-time 60 --retry 3 \
  https://trunk.io/releases/analytics-cli/prod/channel-1.json | cut -d'"' -f4)
curl -fL --connect-timeout 10 --max-time 60 --retry 3 \
  "https://trunk.io/releases/analytics-cli/prod/${VERSION}/${SKU}" \
  | tar -xz

chmod +x trunk-analytics-cli
```

```bash Linux (arm64) theme={"system"}
SKU="trunk-analytics-cli-aarch64-unknown-linux.tar.gz"
VERSION=$(curl -fsSL --connect-timeout 10 --max-time 60 --retry 3 \
  https://trunk.io/releases/analytics-cli/prod/channel-1.json | cut -d'"' -f4)
curl -fL --connect-timeout 10 --max-time 60 --retry 3 \
  "https://trunk.io/releases/analytics-cli/prod/${VERSION}/${SKU}" \
  | tar -xz

chmod +x trunk-analytics-cli
```

```bash macOS (arm64) theme={"system"}
SKU="trunk-analytics-cli-aarch64-apple-darwin.tar.gz"
VERSION=$(curl -fsSL --connect-timeout 10 --max-time 60 --retry 3 \
  https://trunk.io/releases/analytics-cli/prod/channel-1.json | cut -d'"' -f4)
curl -fL --connect-timeout 10 --max-time 60 --retry 3 \
  "https://trunk.io/releases/analytics-cli/prod/${VERSION}/${SKU}" \
  | tar -xz

chmod +x trunk-analytics-cli
```

```bash macOS (x64) theme={"system"}
SKU="trunk-analytics-cli-x86_64-apple-darwin.tar.gz"
VERSION=$(curl -fsSL --connect-timeout 10 --max-time 60 --retry 3 \
  https://trunk.io/releases/analytics-cli/prod/channel-1.json | cut -d'"' -f4)
curl -fL --connect-timeout 10 --max-time 60 --retry 3 \
  "https://trunk.io/releases/analytics-cli/prod/${VERSION}/${SKU}" \
  | tar -xz

chmod +x trunk-analytics-cli
```

## Organization Slug, API Key, and Test Collection

The CLI requires your Trunk organization slug and test collection ID, passed through `--org-url-slug` and `--test-collection-id`, to upload results to the correct organization and collection. They can alternatively be set via environment variables, `TRUNK_ORG_URL_SLUG` and `TRUNK_TEST_COLLECTION_ID`.

You can find your organization slug under **Settings** → **Organization** → **General**. The collection ID is on the collection's page; see [Test Collections](#test-collections).

Uploads also need an API key with the **Upload test results** permission, created under **Settings** → **Developer** → **API Keys**. `trunk flakytests` uses the key stored with `trunk auth api-key set`. When you run the Trunk Analytics CLI directly, pass the key with `--token` or `TRUNK_API_TOKEN`.

> [!NOTE]
>
> Your organization slug is the tail of your dashboard URL (`app.trunk.io/<org-slug>`). It defaults to your organization name with spaces replaced by hyphens. To change it, contact [help@trunk.io](mailto:help@trunk.io).

![The General page, with the organization slug in the URL field](https://mintcdn.com/trunk-4cab4936/RwTjhJZhNhKem-nW/assets/flaky-tests/reference/org-slug-light.png?fit=max\&auto=format\&n=RwTjhJZhNhKem-nW\&q=85\&s=47db9f0caa7b01ef7a08b43fa1a560e5)

Make sure you are getting your Organization Slug, not the Organization Name.

## Uploading Test Results

> [!NOTE]
>
> The uploaded tests are processed by Trunk periodically, not in real-time. Wait for at least an hour after the initial upload before they’re displayed in the [Uploads tab](https://docs.trunk.io/flaky-tests/get-started#step-4-verify-integration). Multiple uploads are required before a test can be accurately detected as flaky.

Trunk accepts uploads from three main report sources, [JUnit XML](https://github.com/testmoapp/junitxml), [Bazel Event Protocol JSONs](https://bazel.build/remote/bep#consuming-bep-text-json), and Swift (both XCode XCResult paths and the XML written by `swift test --xunit-output`). You can upload each of these test report sources using the `trunk flakytests upload` command like this:

> [tab] JUnit XML
>
> Trunk can accept JUnit XMLs through the `--junit-paths` argument:
>
> ```
> trunk flakytests upload --junit-paths "test_output.xml" \
>    --org-url-slug <TRUNK_ORG_URL_SLUG> \
>    --test-collection-id <TRUNK_TEST_COLLECTION_ID>
> ```

> [tab] Bazel
>
> Trunk can accept Bazel through the `--bazel-bep-path` argument:
>
> ```
> trunk flakytests upload --bazel-bep-path <BEP_JSON_PATH> \
>    --org-url-slug <TRUNK_ORG_URL_SLUG> \
>    --test-collection-id <TRUNK_TEST_COLLECTION_ID>
> ```

> [tab] XCode
>
> Trunk can accept XCode through the `--xcresult-path` argument:
>
> ```
> trunk flakytests upload --xcresult-path <XCRESULT_PATH> \
>    --org-url-slug <TRUNK_ORG_URL_SLUG> \
>    --test-collection-id <TRUNK_TEST_COLLECTION_ID>
> ```

> [tab] Swift
>
> Trunk can accept the XML written by `swift test --xunit-output` through the `--swift-test-xunit-paths` argument:
>
> ```
> trunk flakytests upload --swift-test-xunit-paths "junit-swift-testing.xml,junit.xml" \
>    --org-url-slug <TRUNK_ORG_URL_SLUG> \
>    --test-collection-id <TRUNK_TEST_COLLECTION_ID>
> ```
>
> This XML carries no file path for any test case, so Trunk resolves each test to the file it is declared in by reading your checkout. See [Swift Testing](https://docs.trunk.io/flaky-tests/get-started/frameworks/swift-testing.md) for what a single `swift test` run writes and what the resolution requires.

## Variants

If you run the same tests across different environments or architectures, you can use variants to separate these runs into distinct test cases. This allows Trunk to detect environment-specific flakes.

For example, a test for a mobile app might be flaky on iOS but stable on Android. Using variants, Trunk can isolate flakes on the iOS variant instead of marking the test as flaky across all environments.

You can specify a variant during upload using the `--variant` option:

```sh Upload an iOS variant theme={"system"}
trunk flakytests upload --junit-paths "test_output.xml" \
   --org-url-slug <TRUNK_ORG_URL_SLUG> \
   --test-collection-id <TRUNK_TEST_COLLECTION_ID> \
   --variant ios
```

Variant names are displayed in brackets next to test names in your dashboard:

![](https://mintcdn.com/trunk-4cab4936/_uqom5T5LPXKKAze/assets/flaky-tests/reference/variants-light-border.png?fit=max\&auto=format\&n=_uqom5T5LPXKKAze\&q=85\&s=3c98b1d4eddeef12f09eb4872ec4b9a1)

The same test, but the first is a macOS variant.

## Test Collections

[Test collections](https://docs.trunk.io/flaky-tests/test-collections.md) group tests so they can be configured and reviewed together, with their own flake detection and quarantining. Every upload names the collection it belongs to, by passing its ID with `--test-collection-id`:

```sh Upload to a test collection theme={"system"}
trunk flakytests upload --junit-paths "test_output.xml" \
   --org-url-slug <TRUNK_ORG_URL_SLUG> \
   --test-collection-id <COLLECTION_ID>
```

The collection ID is eight alphanumeric characters, and you copy it from the collection in the Trunk app. `--org-url-slug` is still required — the collection ID is an addition to it, not a replacement.

You can set the ID as the `TRUNK_TEST_COLLECTION_ID` environment variable instead, and the [uploader action](https://docs.trunk.io/flaky-tests/get-started/ci-providers/github-actions.md) takes it as the `test-collection-id` input.

> [!NOTE]
>
> Each invocation uploads to a single collection. To send the same results to more than one collection, run the upload once per collection.

> [!WARNING]
>
> CLI versions before 1.0.0 still upload when no collection ID is passed. Trunk routes such an upload to the collection it made for that repository when your organization moved to test collections, and drops the upload if the repository has no such collection. Pass `--test-collection-id` so every upload lands where you expect.

## Running and Quarantining Tests

You can also execute tests and upload results to Trunk in a single step using the `test` command to **wrap** your test command.

This is especially useful for [Quarantining](../quarantining/), where the Trunk Analytics CLI will **override the exit code** of the test command if all failures can be quarantined, **preventing** flaky tests from failing your builds in CI.

> [tab] JUnit XML
>
> Trunk can accept JUnit XMLs through the `--junit-paths` argument:
>
> ```
> trunk flakytests test --junit-paths "test_output.xml" \
>    --org-url-slug <TRUNK_ORG_URL_SLUG> \
>    --test-collection-id <TRUNK_TEST_COLLECTION_ID> \
>    -- <YOUR_TEST_COMMAND>
> ```

> [tab] Bazel
>
> Trunk can accept Bazel through the `--bazel-bep-path` argument:
>
> ```
> trunk flakytests test --bazel-bep-path <BEP_JSON_PATH> \
>    --org-url-slug <TRUNK_ORG_URL_SLUG> \
>    --test-collection-id <TRUNK_TEST_COLLECTION_ID> \
>    -- <YOUR_TEST_COMMAND>
> ```

> [tab] XCode
>
> Trunk can accept XCode through the `--xcresult-path` argument:
>
> ```
> trunk flakytests test --xcresult-path <XCRESULT_PATH> \
>    --org-url-slug <TRUNK_ORG_URL_SLUG> \
>    --test-collection-id <TRUNK_TEST_COLLECTION_ID> \
>    -- <YOUR_TEST_COMMAND>
> ```

> [tab] Swift
>
> Trunk can accept the XML written by `swift test --xunit-output` through the `--swift-test-xunit-paths` argument:
>
> ```
> trunk flakytests test --swift-test-xunit-paths "junit-swift-testing.xml,junit.xml" \
>    --org-url-slug <TRUNK_ORG_URL_SLUG> \
>    --test-collection-id <TRUNK_TEST_COLLECTION_ID> \
>    -- <YOUR_TEST_COMMAND>
> ```

> [!NOTE]
>
> ### Service Availability and Graceful Degradation
>
> Trunk Analytics CLI is designed to fail safe when our quarantine service is unavailable. Read more at [Quarantine Service Availability](https://docs.trunk.io/flaky-tests/quarantining/quarantine-service-availability.md)

### Upload failure vs test failure

We use the `SOFTWARE` exit code (70) if the upload fails.

If you use the `test` command and tests fail without the failures being quarantined, we return the provided exit code from the wrapped execution.

If you use the `upload` command, we return exit code `FAILURE` or the exit code provided with the `--test_process_exit_code` argument.

## Validating reports locally

You can validate the test reports produced by your test frameworks before you set up Trunk in your CI jobs. This is currently **only available for XML reports**.

You can run the validate command like this:

```
trunk flakytests validate --junit-paths "test_output.xml"
```

The `validate` command will output any problems with your reports so you can address them before setting up Trunk in CI.

```sh theme={"system"}
Validating the following 1 files:
  File set matching junit.xml:
    junit.xml

junit.xml - 1 test suites, 0 test cases, 0 validation errors

✅ 1 file found, all fully correct
Navigate to https://app.trunk.io/onboarding?intent=flaky+tests to continue using Trunk Flaky Tests!
```

## Using custom CI systems

The CLI is preconfigured to work with a set [ci-providers](https://docs.trunk.io/flaky-tests/get-started/ci-providers/) but can be used with any CI system by passing [#environment-variables](https://docs.trunk.io/flaky-tests/get-started/ci-providers/otherci.md#environment-variables) to the uploader.

> More information on using [otherci.md](https://docs.trunk.io/flaky-tests/get-started/ci-providers/otherci.md) is documented here.

## Full command reference

`trunk flakytests` (alias `trunk ft`) and `trunk-analytics-cli` accept the following subcommands:

| Command | Description |
| - | - |
| `trunk flakytests upload` | Upload data to Trunk Flaky Tests. |
| `trunk flakytests validate` | Validates the provided JUnit XML files and prints any errors. |
| `trunk flakytests test -- <COMMAND>` | Runs tests using the provided command, uploads results, checks whether the failures are [quarantined](../quarantining/#updates-in-ci) tests, and corrects the exit code based on that. |

The `upload` and `test` commands accept the following options:

| Argument | Description |
| - | - |
| `--junit-paths <JUNIT_PATHS>` | Path to the test output files. File globs are supported. Remember to wrap globs in `""` quotes |
| `--bazel-bep-path <BEP_JSON_PATH>` | Path to a JSON serialized [Bazel Build Event Protocol](https://bazel.build/remote/bep). Trunk will use the BEP file to locate test reports. Your test frameworks must still output [compatible report formats](https://docs.trunk.io/flaky-tests/get-started/frameworks/). |
| `--xcresult-path <XCRESULT_PATH>` | Path to a `.xcresult` directory, which contains test reports from `xcodebuild`. macOS only. |
| `--swift-test-xunit-paths <PATHS>` | Comma-separated list of glob patterns to files written by `swift test --xunit-output`, resolved against the repository root like `--junit-paths`. This XML carries no file path, so each test is attributed to the file it is declared in, resolved from your checkout. Can also be set with the `TRUNK_SWIFT_TEST_XUNIT_PATHS` environment variable. See [Swift Testing](https://docs.trunk.io/flaky-tests/get-started/frameworks/swift-testing.md). |
| `--use-experimental-xcresult-test-locations` | **Beta.** Take each `.xcresult` test's file from where it is declared rather than from the failure that surfaced it, which also gives passing tests a file. macOS only. See [XCTest](https://docs.trunk.io/flaky-tests/get-started/frameworks/xctest.md#attributing-tests-to-their-declaring-file). |
| `--org-url-slug <ORG_URL_SLUG>` | Trunk organization slug, from **Settings** → **Organization** → **General**. |
| `--token <TOKEN>` | An API key with the **Upload test results** permission, from **Settings** → **Developer** → **API Keys**. Defaults to the `TRUNK_API_TOKEN` variable. `trunk flakytests` sets it for you from the key stored with `trunk auth api-key set`, so pass it only when you run the Trunk Analytics CLI directly. The Trunk Analytics CLI 1.0.0 and later refuse the legacy organization token. |
| `-h, --help` | Additional detailed description of the `upload` command. |
| `--repo-root` | Path to the repository root. Defaults to the current directory. |
| `--repo-url <REPO_URL>` | Value to override URL of repository. **Optional**. |
| `--repo-head-sha` `<REPO_HEAD_SHA>` | Value to override SHA of repository head. **Optional**. |
| `--repo-head-branch <REPO_HEAD_BRANCH>` | Value to override branch of repository head. **Optional**. |
| `--repo-head-commit-epoch <REPO_HEAD_COMMIT_EPOCH>` | Value to override commit epoch of repository head. **Optional**. |
| `--codeowners-path <CODEOWNERS_PATH>` | Value to override CODEOWNERS file or directory path. **Optional**. |
| `--use-bazel-target-for-codeowners` | When uploading a Bazel BEP file, use the Bazel target as a fallback path to associate test cases to codeowners. **Optional**. |
| `--allow-empty-test-results` | Don't fail commands if test results are empty or missing. Use it when you sometimes skip all tests for certain CI jobs. Defaults to `true`. |
| `--variant <VARIANT_NAME>` | Upload tests to a specific variant group. **Optional**. |
| `--test-collection-id <COLLECTION_ID>` | Upload to a [test collection](https://docs.trunk.io/flaky-tests/test-collections.md), in addition to (not instead of) `--org-url-slug`. Can also be set with the `TRUNK_TEST_COLLECTION_ID` environment variable. **Required**. |
| `--allow-forked-pr-uploads` | Upload from a forked pull request, whose CI can't read your API key. Requires `--test-collection-id`, and the collection must have forked pull request uploads turned on. Works only in a GitHub Actions run of a pull request from a fork, with the job's `GITHUB_TOKEN` in the environment. See [Uploads from Forked Pull Requests](https://docs.trunk.io/flaky-tests/get-started/fork-pr-uploads.md). Can also be set with the `TRUNK_ALLOW_FORKED_PR_UPLOADS=true` environment variable. **Optional**. |
| `--disable-quarantining` | Report every test failure in the exit code, even for quarantined tests. Can also be set with the `TRUNK_DISABLE_QUARANTINING=true` environment variable. **Optional**. |
| `--test-process-exit-code` `<EXIT_CODE>` | Specify the exit code of the test previously run. This is used by the upload command to identify errors that happen outside of the context of the test execution (such as build errors). |
| `--dry-run` | Write the test results bundle to a local `./bundle_upload` directory instead of uploading it to Trunk. [Quarantining](../quarantining/#quarantining-without-uploading) still runs and still determines the exit code. Can also be set with the `TRUNK_DRY_RUN=true` environment variable. **Optional**. |
| `--summary-output-file <PATH>` | Write a JSON summary of the run to this file: the test counts, and each failed test with its Trunk test ID, whether it was quarantined, and its link. `trunk-analytics-cli summary-output-schema` prints the summary's JSON Schema. See [Explain a Failed Pull Request](https://docs.trunk.io/flaky-tests/recipes/explain-failed-pr-tests.md). Can also be set with the `TRUNK_SUMMARY_OUTPUT_FILE` environment variable. **Optional**. |

> [!NOTE]
>
> **Memory Overhead**
>
> Running tests via `trunk flakytests test` adds negligible memory overhead.
>
> This subcommand is a thin wrapper around your existing test command and doesn't modify or parallelize test execution.
>
> During execution, it:
>
> * Runs your provided test command directly.
> * Records start and end times.
> * Captures the exit code for quarantine decisions.
>
> You can safely run the CLI even with large or memory-intensive suites, without risking additional OOMs in your CI agents.
