Introducing `tuist.toml`

General
1

Hey everyone :wave:

Following the tuist.toml RFC, we’ve shipped tuist.toml as a new way to configure the Tuist CLI without requiring Swift, making it a better fit on Linux if you only want to interact with the server and don’t need macOS-specific functionality like project generation.

If you are using Tuist.swift, nothing changes – tuist.toml is fully optional and we have no plans to ever deprecate Tuist.swift.

Why

When we added Linux support for auth and server commands, we hit an awkward gap: the CLI worked on Linux, but configuring it still required Tuist.swift, which needs a Swift compiler. That meant Android engineers using the upcoming Tuist Gradle plugin, or anyone on a Linux CI machine, had to pass --full-handle and --server-url flags on every single command or make sure Swift was available.

tuist.toml removes that friction. It’s a static file that any platform can read without Swift toolchain required. This file can be useful also for existing iOS teams as commands like tuist test case list, tuist build list, or tuist build show will soon work out of the box on Linux, making it easy to ingest or work with server-side analytical data from a Linux runner, which are typically much cheaper than macOS ones.

The format

project = "org/project"        # required, maps to your project's full handle
url = "https://my.tuist.dev"   # optional, defaults to https://tuist.dev

That’s it. Place a tuist.toml at the root of your repository (next to your .git directory or Tuist/ folder) and the CLI picks it up automatically.

Precedence

Configuration sources are resolved in this order:

  1. CLI flags (highest priority)
  2. Environment variables
  3. Tuist.swift
  4. tuist.toml
  5. Defaults

If you already have a Tuist.swift, it takes precedence — tuist.toml won’t interfere. This makes it easy to adopt incrementally or use it only in environments where Swift isn’t available.

Scope

tuist.toml covers server-interaction settings: project handle and server URL. Generation options, plugins, cache profiles, and Xcode version constraints stay in Tuist.swift. Similarly, configuration specific to the Gradle plugin stays in the Gradle plugin.

What’s next

We’ll be documenting tuist.toml as the recommended configuration format for the upcoming Gradle integration.

If you’re using Tuist on Linux, give it a try and let us know how it goes.