axiom-xctrace-ref

# xctrace CLI Reference

Command-line interface for Instruments profiling. Enables headless performance analysis without GUI.

## Overview

`xctrace` is the CLI tool behind Instruments.app. Use it for:
- Automated profiling in CI/CD pipelines
- Headless trace collection without GUI
- Programmatic trace analysis via XML export
- Performance regression detection

**Requires**: Xcode 12+ (xctrace 12.0+). This reference tested with Xcode 26.2.

## Quick Reference

```bash
# Record a 10-second CPU profile
xcrun xctrace record --instrument 'CPU Profiler' --attach 'MyApp' --time-limit 10s --output profile.trace

# Export to XML for analysis
xcrun xctrace export --input profile.trace --toc  # See available tables
xcrun xctrace export --input profile.trace --xpath '/trace-toc/run[@number="1"]/data/table[@schema="cpu-profile"]'

# List available instruments
xcrun xctrace list instruments

# List available templates
xcrun xctrace list templates
```

## Recording Traces

### Basic Recording

```bash
# Using an instrument (recommended for CLI automation)
xcrun xctrace record --instrument 'CPU Profiler' --attach 'AppName' --time-limit 10s --output trace.trace

# Using a template (may fail on export in Xcode 26+)
xcrun xctrace record --template 'Time Profiler' --attach 'AppName' --time-limit 10s --output trace.trace
```

**Note**: In Xcode 26+, use `--instrument` instead of `--template` for reliable export. Templates may produce traces with "Document Missing Template Error" on export.

### Target Selection

```bash
# Attach to running process by name
xcrun xctrace record --instrument 'CPU Profiler' --attach 'MyApp' --time-limit 10s

# Attach to running process by PID
xcrun xctrace record --instrument 'CPU Profiler' --attach 12345 --time-limit 10s

# Profile all processes
xcrun xctrace record --instrument 'CPU Profiler' --all-processes --time-limit 10s

# Launch and profile
xcrun xctrace record --instrument 'CPU Profiler' --launch -- /path/to/app arg1 arg2

# Target specific device