Logging

The CLI logs messages internally to help you diagnose issues.

Diagnose issues using logs

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

In every run, it creates a log file at $XDG_STATE_HOME/tuist/logs/{uuid}.log 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.

TIP

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

By default, the CLI outputs the logs path when the execution exits unexpectedly. If it doesn't, you can find the logs in the path mentioned above (i.e., the most recent log file).

WARNING

Sensitive information is not redacted, so be cautious when sharing logs.

Continuous integration

In CI, where environments are disposable, you might want to configure your CI pipeline to export Tuist logs. 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 logs 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 logs
        if: failure()
        uses: actions/upload-artifact@v4
        with:
          name: tuist-logs
          path: /tmp/tuist/logs/*.log

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.