Skip to main content
Tuist Previews makes it easy to distribute iOS, macOS, visionOS, and Android app builds to your team for testing and feedback. Upload builds directly from the CLI and share them via a web link.

​
Overview

Previews solve the challenge of app distribution by:
  • Uploading builds directly from the CLI
  • Generating shareable web links for each build
  • Tracking build metadata (version, commit, branch)
  • Organizing builds by track (e.g., staging, production)
  • Supporting multiple platforms (iOS, macOS, visionOS, Android)

​
Prerequisites

  1. Authenticate with Tuist Cloud
  2. Configure your project in Config.swift:
Config.swift
import ProjectDescription

let config = Config(
    cloud: .cloud(
        url: "https://cloud.tuist.io",
        projectId: "your-org/your-project"
    )
)

​
Uploading Previews

​
iOS Previews (IPA)

Upload an IPA file to create a preview: 
tuist build MyApp --platform iOS --configuration Release
tuist share MyApp
The tuist share command:
  1. Locates the built IPA
  2. Extracts app metadata (name, version, bundle ID)
  3. Uploads to Tuist Cloud
  4. Returns a shareable URL
Output: 
✓ Uploading MyApp.ipa...
✓ Preview created successfully

📱 Share this link: https://cloud.tuist.io/preview/abc123

​
macOS Previews (App Bundle)

For macOS apps, upload the .app bundle: 
tuist build MyMacApp --platform macOS --configuration Release
tuist share MyMacApp --platform macOS

​
Android Previews (APK)

Upload Android APK files: 
tuist build MyAndroidApp --platform Android
tuist share MyAndroidApp --platform Android
Tuist automatically detects the build artifact type (IPA, APK, or App bundle) based on the platform.

​
Preview Metadata

​
Git Integration

Tuist automatically captures git metadata when uploading: 
tuist share MyApp
# Automatically includes:
# - Git branch
# - Commit SHA
# - Commit message
Manually specify git information: 
tuist share MyApp \
  --git-branch feature/new-ui \
  --git-commit-sha abc123def \
  --git-ref refs/heads/feature/new-ui

​
Build Tracks

Organize previews by track (e.g., staging, production, alpha): 
tuist share MyApp --track staging
Tracks help organize builds:
  • staging: Internal testing builds
  • production: Production candidates
  • alpha: Early feature previews
  • beta: Public beta builds

​
Version Override

Override the build version for special builds: 
export TUIST_PREVIEW_BUILD_VERSION=1.2.3-hotfix
tuist share MyApp
Or append a suffix: 
export TUIST_PREVIEW_BUILD_VERSION_SUFFIX=beta
tuist share MyApp
# Results in version like: 1.2.3-beta

​
Managing Previews

​
List Previews

View all previews for your project: 
tuist preview list
Filter by track: 
tuist preview list --track staging

​
Preview Details

Get details about a specific preview: 
tuist preview show abc123
Displays:
  • App name and version
  • Upload date and time
  • Git commit information
  • Supported platforms
  • Download/install stats

​
Delete Previews

Remove old previews: 
tuist preview delete abc123
Deleting a preview removes it permanently and invalidates all shared links.
When you upload a preview, you receive a shareable URL: 
https://cloud.tuist.io/preview/abc123
Anyone with the link can:
  • View app details (name, version, icon)
  • Download the build
  • Install on their device (iOS/Android)
  • View git commit information

​
Installing iOS Previews

Recipients can install iOS previews by:
  1. Opening the preview link on their iOS device
  2. Tapping Install
  3. Following iOS installation prompts
iOS previews require the app to be signed with an ad-hoc or enterprise provisioning profile, or the device UDID must be included in the provisioning profile.

​
Installing macOS Previews

For macOS apps:
  1. Open the preview link
  2. Download the .app bundle
  3. Move to Applications folder
  4. Right-click and select Open (first time only)

​
CI/CD Integration

Automate preview uploads in your CI pipeline:

​
GitHub Actions Example

.github/workflows/preview.yml
name: Upload Preview
on:
  push:
    branches: [develop, staging]

jobs:
  preview:
    runs-on: macos-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Install Tuist
        run: curl -Ls https://install.tuist.io | bash
      
      - name: Authenticate
        run: tuist auth login
      
      - name: Build app
        run: tuist build MyApp --platform iOS --configuration Release
      
      - name: Upload preview
        run: tuist share MyApp --track staging
        
      - name: Comment PR with preview link
        uses: actions/github-script@v7
        with:
          script: |
            const previewUrl = process.env.PREVIEW_URL;
            await github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: `📱 Preview build ready: ${previewUrl}`
            });

​
GitLab CI Example

.gitlab-ci.yml
preview:
  stage: deploy
  only:
    - develop
    - staging
  script:
    - curl -Ls https://install.tuist.io | bash
    - tuist auth login
    - tuist build MyApp --platform iOS --configuration Release
    - tuist share MyApp --track staging
  artifacts:
    reports:
      dotenv: preview.env

​
Preview Features

​
App Icons

Tuist automatically extracts and displays the app icon in the preview:
  • iOS: Extracted from the IPA
  • macOS: Extracted from the app bundle
  • Android: Extracted from the APK

​
Multi-Platform Support

A single preview can support multiple platforms: 
tuist share MyApp --platforms iOS,visionOS
Users can choose which platform to install based on their device.

​
Preview Expiration

Previews can be configured to expire automatically:
Config.swift
let config = Config(
    cloud: .cloud(
        url: "https://cloud.tuist.io",
        projectId: "your-org/your-project",
        options: .options(
            previewExpirationDays: 30
        )
    )
)

​
QA Integration

QA Service

Learn how to organize previews for QA workflows

​
Advanced Usage

​
Custom Upload Progress

Monitor upload progress in scripts: 
tuist share MyApp --verbose

​
Parallel Uploads

Upload multiple builds in parallel: 
tuist share MyApp --platform iOS &
tuist share MyApp --platform macOS &
wait

​
Preview Webhooks

Configure webhooks to notify external services when previews are uploaded:
Config.swift
let config = Config(
    cloud: .cloud(
        url: "https://cloud.tuist.io",
        projectId: "your-org/your-project",
        options: .options(
            webhooks: [
                .webhook(
                    url: "https://your-webhook.com/preview-uploaded",
                    events: [.previewUploaded]
                )
            ]
        )
    )
)

​
Troubleshooting

​
Upload Fails

If preview upload fails:
  1. Check authentication: tuist auth whoami
  2. Verify network connectivity
  3. Ensure the build artifact exists
  4. Check disk space
If the preview link doesn’t work:
  • Verify the preview wasn’t deleted
  • Check that the recipient has access permissions
  • Ensure the preview hasn’t expired

​
Installation Fails (iOS)

If iOS installation fails:
  • Verify the device UDID is in the provisioning profile
  • Check that the app is signed correctly
  • Ensure the device trusts the signing certificate

​
Best Practices

Create separate tracks for different testing stages (alpha, beta, staging, production).
Upload previews automatically on every merge to develop or staging branches.
Always include git branch and commit information to help QA track down issues.
Configure automatic expiration to save storage space and avoid confusion with old builds.

​
Next Steps

QA Service

Streamline QA workflows with organized preview management

Build Insights

Track preview usage and download metrics