trunk CLI uploads your test results to Trunk Flaky Tests. You install it once, store a Trunk API key with it, and run trunk flakytests (or its alias, trunk ft) after your tests. The CLI downloads the Trunk Analytics CLI (trunk-analytics-cli) on first use, runs it with your arguments, and passes it your credential.
To upload from GitHub Actions, use the trunk-io/analytics-uploader action, which installs and runs the trunk CLI for you.
Install the trunk CLI
- macOS and Linux
- Windows (experimental)
- Linux on x64 and arm64. One static build runs on any distribution, including Alpine and minimal containers.
- macOS 14 (Sonoma) or later, on Apple silicon and Intel Macs.
trunk to /usr/local/bin when that directory is writable, and to ~/.local/bin otherwise. It never runs sudo. If the install directory isn’t on your PATH, the installer prints the line to add to your shell profile. Pass --install-dir <DIR> to install somewhere else.trunk and a version number, such as trunk 1.2.3.
If you already have the older
trunk CLI for Code Quality on your PATH, the installer warns you and installs the new CLI anyway. Make sure the new CLI’s directory comes first on your PATH, or remove the old one. The older CLI prints a bare version number for trunk --version.Create an API key
trunk flakytests uploads with a Trunk API key that has the Upload test results permission.
- In the Trunk app, navigate to Settings → Developer → API Keys and click the Create Key button.
- Name the key after what will use it, such as
flaky-tests-ci. - Select the Upload test results permission.
- Copy the key. It starts with
trunk_v2_and is shown only once.
Store the API key
Runtrunk auth api-key set and paste the key at the prompt:
TRUNK_ORG_API_KEY environment variable is set, the command reads the key from it instead of prompting. Use it in CI, where there’s no terminal to prompt on:
403. The command never takes the key as an argument, so the key stays out of your shell history and process listings.
The key is stored in ~/.config/trunk-cli/credentials.json (%APPDATA%\trunk-cli\credentials.json on Windows), readable only by you. To remove it, run trunk auth api-key clear.
trunk auth login signs you in as yourself, for commands such as trunk mergequeue. It doesn’t authorize uploads: trunk flakytests uses only the stored API key.Upload test results
Runtrunk flakytests upload after your tests, from the root of your repository:
--org-url-slugis your organization slug, from Settings → Organization → General.--test-collection-idis the ID of the test collection to upload to, from the collection’s page header. It’s required.
trunk flakytests test. Put the test command after --:
trunk flakytests test exits with 0, so known flaky tests don’t fail your build.
trunk flakytests accepts every Trunk Analytics CLI command and option, such as --bazel-bep-path, --xcresult-path, --variant, and validate. See the CLI reference for the full list, or run trunk flakytests upload --help.
Use the trunk CLI in CI
Store the API key as a secret in your CI provider, such asTRUNK_API_KEY. Then add these steps to each job that runs tests:
PATH, add the directory to PATH for the later steps, or pass --install-dir with a directory that is.
Upload from jobs on pull requests and on your stable branches, such as main. For provider-specific setup, see CI Providers.
You can skip trunk auth api-key set and set TRUNK_API_TOKEN to the API key on the trunk flakytests step instead. When TRUNK_API_TOKEN or --token is set, trunk flakytests passes it to the Trunk Analytics CLI unchanged.
Pin versions
By default, the installer installs the latesttrunk CLI, and trunk flakytests runs the latest Trunk Analytics CLI. To get the same versions on every run, pin them:
-
trunk CLI. Pass
--versionto the installer. A pinned install doesn’t update itself.On Windows, runiex "& {$(irm https://install.trunk.io/install.ps1)} -Version <VERSION>". -
Trunk Analytics CLI. Set
TRUNK_ANALYTICS_CLI_VERSIONto a version, such as1.0.0. ThetrunkCLI downloads each version once and caches it.
TRUNK_ANALYTICS_CLI_VERSION to a 0.17.x release and pass the token with --token or TRUNK_API_TOKEN. The trunk CLI passes a stored API key only to 1.0.0 and later.
Updates
Thetrunk CLI updates itself. Once a day it checks for a new version in the background and switches to it on the next run. It doesn’t check when:
CIis set totrue. Most CI providers, including GitHub Actions, set it for you.TRUNK_NO_AUTO_UPDATEis set to any value.- The install is pinned to a version.
trunk update. It works even when automatic updates are off, and it removes a version pin.
Telemetry
Thetrunk CLI sends usage telemetry, such as the command name and its exit code, while you’re signed in with trunk auth login or have an API key stored. A fork pull request upload with no API key sends none. To turn telemetry off, set TRUNK_TELEMETRY=0 or DO_NOT_TRACK=1. trunk auth status shows whether telemetry is on.