Tuist authentication

authentication.md

Tuist CLI Authentication Flow

sequenceDiagram
    participant User
    participant CLI as Tuist CLI
    participant Browser
    participant Server as Tuist Server
    participant Storage as Storage

    %% === INITIAL LOGIN ===
    rect rgb(230, 245, 255)
        Note over User,Server: Initial Login (one-time setup)
        User->>CLI: tuist auth login
        CLI->>Browser: Opens login page
        Browser->>Server: User authenticates (SSO/Email)
        Server-->>CLI: Access Token (10 min) + Refresh Token (4 weeks)
        CLI->>CLI: Stores tokens locally
    end

    %% === USING THE CLI ===
    rect rgb(230, 255, 230)
        Note over User,Storage: Using the CLI (e.g., generating a project)
        User->>CLI: tuist generate

        alt Token still valid
            CLI->>CLI: Use stored access token
        else Token expired or expiring soon
            CLI->>Server: Refresh token
            Server-->>CLI: New access token
        end

        CLI->>Server: Request artifact<br/>(with access token)
        Server->>Server: Validate token & permissions
        Server->>Server: Generate time-limited download URL
        Server-->>CLI: Pre-signed URL (valid 1 hour)
        CLI->>Storage: Download artifact directly
        Storage-->>CLI: Binary artifact
    end

Loading

How It Works

1. Login: Run tuist auth login once to authenticate via your browser
2. Token Storage: Credentials are stored securely on your machine
3. Automatic Refresh: Tokens are refreshed automatically - no manual re-login needed
4. Secure Downloads: Artifacts are downloaded via time-limited URLs directly from storage

Token Lifetimes

Token	Lifetime	Purpose
Access Token	10 minutes	Authenticates API requests
Refresh Token	4 weeks	Obtains new access tokens automatically
Download URL	1 hour	Direct download from storage

CI/CD Authentication

For CI/CD pipelines, use a project token instead of interactive login:

export TUIST_CONFIG_TOKEN=tuist_xxxxx
tuist generate

Project tokens never expire and are scoped to a single project.