Install the Gradle plugin

Install the Gradle plugin {#install-the-gradle-plugin}

Tuist provides a Gradle plugin that integrates with your Gradle project to enable features like remote build caching and build insights. This guide walks you through installing and configuring the plugin.

::: warning REQUIREMENTS

• Tuist CLI 4.138.1 or later
• A Gradle project

:::

1. Initialize Tuist {#initialize-tuist}

Run the following command in your Gradle project root:

::: code-group

mise x tuist@latest -- tuist init

tuist init

:::

The command will walk you through authenticating, creating or selecting a Tuist project, and generating the configuration for your Gradle project.

2. Apply the plugin {#apply-the-plugin}

After running tuist init, you’ll need to add the Tuist plugin to your settings.gradle.kts as instructed by the command output:

plugins {
    id("dev.tuist") version "0.1.0"
}

3. Authenticate your team and CI {#authenticate}

While tuist init authenticates you locally, your teammates and CI environments will need to authenticate separately.

Each teammate should run the following to get access to the Tuist features on their machine:

tuist auth login

For CI, follow the CI authentication guide to configure authentication for your environment.

Configuration reference {#configuration-reference}

The following options are available in the tuist extension block in settings.gradle.kts:

Option	Type	Default	Description
project	String?	null (optional)	The project identifier in account/project format. If not set, the plugin reads it from tuist.toml through the Tuist CLI.
executablePath	String?	null (uses tuist from PATH)	Path to the Tuist CLI executable.
url	String?	null	The base URL of the Tuist server. If not set, it defaults to "https://tuist.dev" or the value defined in tuist.toml.
uploadInBackground	Boolean?	null	Whether to upload build and test insights in the background. When null (default), uploads run in the background for local builds and in the foreground on CI.

::: info TUIST.TOML

The recommended way to configure project (and optionally url) is through a tuist.toml file in your project root. This way the configuration is shared between the Tuist CLI and the Gradle plugin. You can still override these values in settings.gradle.kts if needed.

:::

Next steps {#next-steps}

Once the plugin is installed and configured, you can enable:

• Remote build cache to share build artifacts across your team and CI.
• Build insights to track task timings and cache behavior in the Tuist dashboard.
• Test insights to track test performance and detect flaky tests.
• Flaky tests to automatically detect, track, and quarantine flaky tests.