Parallel File Output for Task Logs

[anatoly314]

Goals

• Enable writing task logs to files in parallel with existing UI modes (TUI/stream)
• Preserve logs from persistent/dev tasks that currently aren't saved anywhere
• Allow users to search, grep, and copy logs while still using TUI's organized view
• Support per-task log separation for easier debugging

Non-goals

• Replacing or modifying the existing TUI/stream UI modes
• Implementing log rotation (delegate to external tools like logrotate)
• Production-grade log shipping (this is for local development and CI)

Background

TUI Usability Limitations

The TUI mode introduced in Turborepo 2.0, while visually appealing, has significant usability issues:

• Cannot copy/paste text - Turbo 2 UI: Can't copy terminal outputs #8372 (65+ upvotes)
• Scrolling is slow and difficult - throttled scroll makes navigating large logs painful
• Cannot search across logs - no grep/ctrl+f capability
• Links are broken by line wrapping - CMD+click doesn't work
• Cannot double-click to select - standard terminal behavior is broken

See also: #10491 "TUI is really hard to use"

Current workaround: Users must switch to --ui=stream, losing the organized task view entirely.

No Runtime Log Persistence for Dev Tasks

For persistent/dev tasks (cache: false), Turborepo does not write logs to files. This creates problems for:

• Local observability testing: Cannot test OpenTelemetry collectors, Fluentd, or similar tools locally before deploying to production
• Post-mortem debugging: Logs are lost when the terminal closes
• Log aggregation: Cannot centralize logs from multiple workspaces
• CI artifact preservation: Runtime logs aren't captured as build artifacts

Current workaround: pnpm dev 2>&1 | tee logs/dev.log - but this:

• Doesn't work well with TUI mode
• Requires wrapper scripts in every project
• Loses per-task separation
• Doesn't integrate with Turborepo's task management

Stream Mode Interleaving

In stream mode, logs from multiple concurrent tasks are interleaved, making it difficult to:

• Follow a specific task's output
• Extract logs for a single package
• Share logs with teammates for debugging

Proposal

Add a fileOutput option that writes logs to files alongside the existing UI, not instead of it.

Configuration

// turbo.json
{
  "$schema": "https://turborepo.com/schema.json",
  "ui": "tui",
  "fileOutput": {
    "enabled": true,
    "path": ".turbo/logs",
    "mode": "per-task",
    "format": "plain",
    "append": false,
    "includeTimestamps": true
  }
}

CLI Flag

# Enable with defaults
turbo run dev --file-output

# Specify path
turbo run dev --file-output=./logs

# Combined with TUI
turbo run dev --ui=tui --file-output=./logs

Example Workflow

# Terminal 1: Interactive TUI for visual organization
turbo run dev --file-output=./logs

# Terminal 2: Search/grep logs in real-time
tail -f ./logs/web#dev.log | grep "error"

Output Modes

Mode	Behavior	Use Case
per-task	Separate file per task: web#dev.log, api#dev.log	Debugging specific packages
unified	Single file with task prefixes	Log aggregation

Output Formats

Format	Description
plain	Raw output, ANSI codes stripped
ansi	Preserve ANSI color codes
json	Structured JSON lines (NDJSON) for tooling integration

---

I'm interested in contributing to this feature if there's appetite for it.

Related Issues

• Turbo 2 UI: Can't copy terminal outputs #8372 - Can't copy terminal outputs (65+ 👍)
• TUI is really hard to use #10491 - TUI is really hard to use
• Output parser for custom logs #10230 - Output parser for custom logs
• Run TurboRepo Across Multiple Terminal Tabs #7486 - Run across multiple terminal tabs

[anthonyshew]

Appreciate you taking the time to create a complete proposal!

Non-persistent tasks are already written to disk in the turbo/.cache directory. We tried to do this for persistent tasks, too, but saw too much bad behavior from tooling filewatchers that were looping due to naively watching the entire directory for the package.

It's likely that there will be some turbo logs command in the near future to simplify grabbing these logs, but we have some pre-work to do first.

Additionally, as far as the other TUI gripes mentioned go, I'll consider those separate but related to the problem of fetching logs. Some are simply usability issues that need shoring up.