tuist run

Run a preview or scheme from your project

Overview

The tuist run command runs a preview, app specifier, or scheme from a Tuist-generated project. It provides a convenient way to launch apps without opening Xcode.

Usage

tuist run [options] <runnable> [arguments...]

Options

--path · string · default: "."

The path to the directory that contains the project with the target or scheme to be run.

-p · string

Short form of --path.

--device · string

The device name to run on (e.g., “iPhone 15 Pro”).

--generate · boolean · default: "false"

Force the generation of the project before running.

--clean · boolean · default: "false"

Clean the project before running.

--configuration · string

The configuration to be used when building the scheme (e.g., Debug, Release).

-C · string

Short form of --configuration.

--os · string

The OS version of the simulator.

-o · string

Short form of --os.

--rosetta · boolean · default: "false"

Append arch=x86_64 to the destination to run the simulator in Rosetta mode.

Arguments

runnable · string · required

One of:

• A preview URL (e.g., https://preview.tuist.dev/...)
• An app specifier (e.g., App@latest or App@feature-branch)
• A scheme name from your generated project (macOS only)

arguments · string[]

Arguments to pass to the application during execution. All arguments after the runnable are forwarded to the app.

Examples

Run by scheme name (macOS)

tuist run MyApp

Runs the MyApp scheme from your generated project.

Run with app specifier

tuist run App@latest

Runs the latest version of App from the preview system.

Run with branch specifier

tuist run App@feature-branch

Runs the App build from the feature-branch.

Run preview URL

tuist run https://preview.tuist.dev/abc123

Runs an app from a preview link.

Run on specific device

tuist run --device "iPhone 15 Pro" MyApp

Runs MyApp on the iPhone 15 Pro simulator.

Run with generation

tuist run --generate MyApp

Generates the workspace first, then runs MyApp.

Run with configuration

tuist run --configuration Release MyApp

Runs MyApp using the Release configuration.

Run with app arguments

tuist run MyApp -- --verbose --config debug

Runs MyApp and passes --verbose and --config debug to the app.

Run with specific OS version

tuist run --os 17.0 --device "iPhone 15" MyApp

Runs MyApp on iPhone 15 with iOS 17.0.

Run in Rosetta mode

tuist run --rosetta MyApp

Runs MyApp in Rosetta mode for Intel compatibility on Apple Silicon.

Runnable types

Scheme name (macOS only)

Run a scheme from your generated Tuist project:

tuist run MyAppScheme

App specifier

Run an app using an identifier and version/branch:

tuist run MyApp@latest         # Latest version
tuist run MyApp@v1.2.3         # Specific version
tuist run MyApp@feature-login  # Specific branch

Preview URL

Run an app from a preview link:

tuist run https://preview.tuist.dev/your-preview-id

App arguments

Pass arguments to your app by adding them after the runnable:

tuist run MyApp -- --my-flag value --another-flag

All arguments after -- are forwarded to the app’s launch arguments.

Requirements

• For preview URLs and app specifiers: Tuist account and authentication (tuist auth)
• For scheme names: Generated Xcode project
• macOS with Xcode installed

Related

• Generate command
• Build command
• Share command