Quickstart

Get started with Tuist in 5 minutes

Quickstart Guide

This guide will help you get started with Tuist, from installation to creating your first generated project.

What you’ll accomplish

1. Install Tuist

   Set up Tuist on your development machine

2. Initialize a project

   Create a new project with Tuist or integrate an existing one

3. Generate and build

   Generate your Xcode project and build your app

4. Explore features

   Learn about caching, testing, and cloud services

Prerequisites

macOS

macOS 12.0 or later (for Xcode projects)

Xcode

Xcode 14.0 or later installed

Swift

Swift 5.9 or later

Command Line Tools

Xcode Command Line Tools installed

Tuist also runs on Linux for commands that don’t require Xcode, such as authentication, project management, and analytics.

Step 1: Install Tuist

The recommended way to install Tuist is using Mise, a versatile development tool version manager:

Install Mise (Homebrew)

brew install mise

curl https://mise.run | sh

Once Mise is installed, you can run Tuist commands directly:

Run Tuist via Mise

mise x tuist@latest -- tuist init

For persistent installation in your project:

Install Tuist in project

cd your-project
mise use tuist@latest

This creates a .mise.toml file that pins the Tuist version for your project, ensuring all team members use the same version.

See the Installation guide for other installation methods including direct download and building from source.

Step 2: Initialize your project

New project

Create a new project from scratch with Tuist’s interactive setup:

Create new project

tuist init

The interactive CLI will guide you through:

1. Authentication: Log in to Tuist Cloud (free tier available)
2. Project type: Choose to create a generated project
3. Project name: Enter your app name
4. Platform: Select iOS, macOS, tvOS, watchOS, or visionOS
5. Organization: Choose or create an organization

What gets created?

Tuist generates a complete project structure:

YourApp/
├── Project.swift          # Project manifest
├── Config.swift           # Tuist configuration (optional)
├── YourApp/
│   ├── Sources/          # Source files
│   │   └── ContentView.swift
│   └── Resources/        # Assets and resources
│       └── Assets.xcassets
├── .mise.toml            # Tuist version pinning
└── .gitignore            # Ignores generated files

• Project.swift: Swift-based project definition
• Sources/: Your application code
• Resources/: Assets, storyboards, and other resources

Existing Xcode project

If you have an existing Xcode project, Tuist can integrate with it:

Initialize in existing project

cd your-existing-project
tuist init

1. Select workflow

   Choose “Integrate with existing Xcode project” when prompted

2. Select project

   Tuist detects your .xcodeproj or .xcworkspace files

3. Configure integration

   Connect to Tuist Cloud for caching and insights

For migrating an existing Xcode project to a generated project, see the migration guide for detailed steps.

Step 3: Generate and build

Once your project is set up, generate the Xcode project:

Generate Xcode project

tuist generate

This command:

• Reads your Project.swift manifest
• Resolves dependencies
• Generates an .xcodeproj or .xcworkspace
• Opens it in Xcode (unless you use --no-open)

Generate and open

tuist generate

tuist generate --no-open

tuist clean && tuist generate

Build your project

You can build using Xcode or directly from the command line:

Build with Tuist

tuist build

tuist build MyApp

tuist build MyApp && tuist run MyApp

Run tests

Run all tests

tuist test

Run specific test target

tuist test MyAppTests

Use tuist test --help to see all testing options including selective testing.

Step 4: Explore features

Now that you have a working project, explore Tuist’s powerful features:

Cache for faster builds

Enable caching to speed up your builds:

Config.swift

import ProjectDescription

let config = Config(
    cache: .cache(
        profiles: [
            .profile(name: "Development", configuration: "Debug")
        ]
    )
)

Warm the cache:

tuist cache warm

Learn more about caching

Discover how to optimize build times with Tuist’s intelligent caching

Visualize your project graph

Understand your project’s dependencies:

Generate dependency graph

tuist graph

This opens an interactive visualization showing:

• Target dependencies
• External packages
• Dependency relationships

Share previews

Share your app with stakeholders:

Share app preview

tuist share MyApp

This uploads your app and provides a shareable link that anyone can use to install the app on their device.

Preview documentation

Learn about app previews and distribution

Understanding the Project.swift manifest

Your Project.swift file defines your project structure:

Project.swift

import ProjectDescription

let project = Project(
    name: "MyApp",
    targets: [
        .target(
            name: "MyApp",
            destinations: .iOS,
            product: .app,
            bundleId: "com.company.myapp",
            deploymentTargets: .iOS("16.0"),
            infoPlist: .default,
            sources: ["MyApp/Sources/**"],
            resources: ["MyApp/Resources/**"],
            dependencies: []
        ),
        .target(
            name: "MyAppTests",
            destinations: .iOS,
            product: .unitTests,
            bundleId: "com.company.myapp.tests",
            sources: ["MyAppTests/Sources/**"],
            dependencies: [
                .target(name: "MyApp")
            ]
        )
    ]
)

Project manifest reference

Explore all Project.swift options and configuration

Common commands

Here are the most frequently used Tuist commands:

Initialize project

tuist init

tuist generate

tuist build [scheme]

tuist test [target]

tuist clean

tuist cache warm

tuist share [scheme]

tuist graph

Full CLI reference

See all available commands and options

What’s next?

Core Concepts

Understand Tuist’s architecture and design principles

Project Structure

Learn how to organize your code and modules

Dependencies

Manage Swift packages and framework dependencies

Build Optimization

Speed up builds with caching and optimization techniques

CI/CD Integration

Set up continuous integration with Tuist

Cloud Services

Explore Tuist’s cloud platform features

Need help?

Documentation

Browse the full documentation

Community

Ask questions in our community forum

Slack

Join the Slack workspace