Trunk Flaky Tests CLI reference

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

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.

Guides by Test Frameworks

Guides by CI Provider

The CLI should be downloaded as part of your test workflow in your CI system. You can download the appropriate binary for your platform directly from the GitHub releases page.

Manual Download

You can find the list of releases on the GitHub release page. We provide executables for Linux and OS X. It’s a single file inside a tar and upon downloading the tar you will find a single binary - trunk-analytics-cli to use.

SKU="trunk-analytics-cli-x86_64-unknown-linux.tar.gz"
curl -fL --retry 3 \
  "https://github.com/trunk-io/analytics-cli/releases/latest/download/${SKU}" \
  | tar -xz

chmod +x trunk-analytics-cli

SKU="trunk-analytics-cli-aarch64-unknown-linux.tar.gz"
curl -fL --retry 3 \
  "https://github.com/trunk-io/analytics-cli/releases/latest/download/${SKU}" \
  | tar -xz

chmod +x trunk-analytics-cli

SKU="trunk-analytics-cli-aarch64-apple-darwin.tar.gz"
curl -fL --retry 3 \
  "https://github.com/trunk-io/analytics-cli/releases/latest/download/${SKU}" \
  | tar -xz

chmod +x trunk-analytics-cli

SKU="trunk-analytics-cli-x86_64-apple-darwin.tar.gz"
curl -fL --retry 3 \
  "https://github.com/trunk-io/analytics-cli/releases/latest/download/${SKU}" \
  | tar -xz

chmod +x trunk-analytics-cli

Organization Slug and Token

The CLI requires your Trunk organization slug and token passed through --org-url-slug and --token to upload results to the correct organization. They can alternatively be set via environment variables, TRUNK_ORG_URL_SLUG and TRUNK_API_TOKEN, respectively. You can find your organization slug and token by navigating to Settings → Organization → General.

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.

Slug
Token

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

Uploading Test Results

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. Multiple uploads are required before a test can be accurately detected as flaky.

Trunk accepts uploads in three main report formats, XML, Bazel Event Protocol JSONs, and XCode XCResult paths. You can upload each of these test report formats using the ./trunk-analytics-cli upload command like this:

XML
Bazel
XCode

Trunk can accept JUnit XMLs through the --junit-paths argument:

./trunk-analytics-cli upload --junit-paths "test_output.xml" \
   --org-url-slug <TRUNK_ORG_URL_SLUG> \
   --token $TRUNK_API_TOKEN

Trunk can accept Bazel through the --bazel-bep-path argument:

./trunk-analytics-cli upload --bazel-bep-path <BEP_JSON_PATH> \
   --org-url-slug <TRUNK_ORG_URL_SLUG> \
   --token $TRUNK_API_TOKEN

Trunk can accept XCode through the --xcresult-path argument:

./trunk-analytics-cli upload --xcresult-path <XCRESULT_PATH> \
   --org-url-slug <TRUNK_ORG_URL_SLUG> \
   --token $TRUNK_API_TOKEN

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:

Upload an iOS variant

./trunk-analytics-cli upload --junit-paths "test_output.xml" \
   --org-url-slug <TRUNK_ORG_URL_SLUG> \
   --token $TRUNK_API_TOKEN \
   --variant ios

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

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

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

XML
Bazel
XCode

Trunk can accept JUnit XMLs through the --junit-paths argument:

./trunk-analytics-cli test --junit-paths "test_output.xml" \
   --org-url-slug <TRUNK_ORG_URL_SLUG> \
   --token $TRUNK_API_TOKEN \
   <YOUR_TEST_COMMAND>

Trunk can accept Bazel through the --bazel-bep-path argument:

./trunk-analytics-cli test --bazel-bep-path <BEP_JSON_PATH> \
   --org-url-slug <TRUNK_ORG_URL_SLUG> \
   --token $TRUNK_API_TOKEN \
   <YOUR_TEST_COMMAND>

Trunk can accept XCode through the --xcresult-path argument:

./trunk-analytics-cli test --xcresult-path <XCRESULT_PATH> \
   --org-url-slug <TRUNK_ORG_URL_SLUG> \
   --token $TRUNK_API_TOKEN \
   <YOUR_TEST_COMMAND>

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

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

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 but can be used with any CI system by passing #environment-variables to the uploader.

More information on using otherci.md is documented here.

Full command reference

The trunk command-line tool can upload and analyze test results. The trunk-analytics-cli command accepts the following subcommands:

Command	Description
`trunk-analytics-cli upload`	Upload data to Trunk Flaky Tests.
`trunk-analytics-cli validate`	Validates if the provided JUnit XML files and prints any errors.
`trunk-analytics-cli test <COMMAND>`	Runs tests using the provided command, uploads results, checks whether the failures are quarantined tests, and correct 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. Trunk will use the BEP file to locate test reports. Your test frameworks must still output compatible report formats.
`--xcresult-path <XCRESULT_PATH>`	Path to a `.xcresult` directory, which contains test reports from `xcodebuild`.
`--org-url-slug <ORG_URL_SLUG>`	Trunk Organization slug, from the Settings page.
`--token <TOKEN>`	Trunk Organization (not repo) token, from the Settings page. Defaults to the `TRUNK_API_TOKEN` variable.
`-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-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).

Memory OverheadRunning tests via trunk-analytics-cli 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.

​Guides

Guides by Test Frameworks

Guides by CI Provider

​Manual Download

​Organization Slug and Token

​Uploading Test Results

​Variants

​Running and Quarantining Tests

​Service Availability and Graceful Degradation

​Upload failure vs test failure

​Validating reports locally

​Using custom CI systems

​Full command reference

Guides

Manual Download

Organization Slug and Token

Uploading Test Results

Variants

Running and Quarantining Tests

Service Availability and Graceful Degradation

Upload failure vs test failure

Validating reports locally

Using custom CI systems

Full command reference