Debugging

Debugging {#debugging}

Tuist provides several tools to help you diagnose issues when commands don’t behave as expected.

::: warning

Session data may contain sensitive information such as file paths, project names, and request/response bodies. While sensitive headers (like Authorization) are redacted, be mindful when sharing session data with others.

:::

Session data {#session-data}

If a command invocation doesn’t yield the intended results, you can diagnose the issue by inspecting the session data. The CLI forwards the logs to OSLog and the file-system.

In every run, it creates a session directory at $XDG_STATE_HOME/tuist/sessions/{uuid}/ where $XDG_STATE_HOME takes the value ~/.local/state if the environment variable is not set. You can also use $TUIST_XDG_STATE_HOME to set a Tuist-specific state directory, which takes precedence over $XDG_STATE_HOME.

Each session directory contains:

• logs.txt - Text logs from the CLI session
• network.har - HTTP Archive (HAR) file containing all network requests and responses made during the session

Visualizing HAR files {#visualizing-har-files}

The HAR file records all HTTP requests and responses made during the session, which is useful for debugging server communication issues. You can open HAR files with several tools:

• Proxyman: A native macOS app for viewing and analyzing HTTP traffic. Import the HAR file via File > Import.
• Browser Developer Tools: Chrome, Firefox, and Safari all support importing HAR files in their Network tab.
• HAR Viewer: A web-based HAR file viewer.

::: tip

Learn more about Tuist’s directory organization and how to configure custom directories in the Directories documentation.

:::

By default, the CLI outputs the session path when the execution exits unexpectedly. If it doesn’t, you can find the session data in the path mentioned above (i.e., the most recent session directory).

Session directories older than 5 days are automatically cleaned up.

Continuous integration {#diagnose-issues-using-logs-ci}

In CI, where environments are disposable, you might want to configure your CI pipeline to export Tuist session data. Exporting artifacts is a common capability across CI services, and the configuration depends on the service you use. For example, in GitHub Actions, you can use the actions/upload-artifact action to upload the session data as an artifact:

name: Node CI

on: [push]

env:
  TUIST_XDG_STATE_HOME: /tmp

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
      # ... other steps
      - run: tuist generate
      # ... do something with the project
      - name: Export Tuist session data
        if: failure()
        uses: actions/upload-artifact@v4
        with:
          name: tuist-sessions
          path: /tmp/tuist/sessions/

Cache daemon debugging {#cache-daemon-debugging}

For debugging cache-related issues, Tuist logs cache daemon operations using os_log with the subsystem dev.tuist.cache. You can stream these logs in real-time using:

log stream --predicate 'subsystem == "dev.tuist.cache"' --debug

These logs are also visible in Console.app by filtering for the dev.tuist.cache subsystem. This provides detailed information about cache operations, which can help diagnose cache upload, download, and communication issues.