Install the Gradle plugin

NOT GENERALLY AVAILABLE

This feature is not generally available yet. If you are interested in trying it out, please reach out to us at [email protected].

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.

REQUIREMENTS

• A Tuist account and project
• Tuist CLI 4.138.1 or later
• A Gradle project

1. Apply the plugin

Add the Tuist plugin to your settings.gradle.kts:

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

2. Configure the project

Create a tuist.toml file in your project root with your project handle:

project = "your-org/your-project" # Optional: can be set here or in settings.gradle.kts

The Gradle plugin reads this file through the Tuist CLI, so you only need to define your project handle in one place. If project is not set in settings.gradle.kts, the plugin falls back to tuist.toml.

NOTE

You can also set project directly in the tuist block in settings.gradle.kts instead of using tuist.toml. However, we recommend tuist.toml so the configuration is shared across Tuist CLI commands and the Gradle plugin.

3. Authenticate

The plugin uses the Tuist CLI authentication flow and reads credentials from the same sources as other Tuist tooling. Follow Gradle plugin authentication for setup details, including CI and self-hosted server configuration.

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.

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

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

• Gradle remote build cache to share build artifacts across your team and CI.
• Gradle build insights to track task timings and cache behavior in the Tuist dashboard.