Skip to content

Getting Started

Prerequisites

  • Python >= 3.10
  • adb in PATH (only required for trace commands)

Installation

Via pip

pip install perfetto-cli

Via uvx (no install)

uvx perfetto-cli --help

From source

git clone https://github.com/SYKernel/perfetto-cli.git
cd perfetto-cli
pip install -e ".[dev]"

AI Tool Integration (Optional)

perfetto-cli provides a skills system that integrates with AI coding assistants. Once installed, AI tools can automatically understand and use perfetto-cli for trace analysis.

Supported AI tools: Claude Code, Cursor, Codex, Gemini CLI, OpenCode

# Interactive install β€” detects your AI tools and guides you through setup
perfetto-cli skills install

# Or install all skills to all detected tools at once
perfetto-cli skills install --all --target all --scope global

# Check installation status
perfetto-cli skills list

After installation, you can ask your AI assistant naturally β€” it will automatically run the appropriate perfetto-cli commands and interpret the results. See AI-Powered Usage for full documentation.

Your First Analysis

1. Get a trace file

Either capture from a device:

perfetto-cli trace start --duration 10s
perfetto-cli trace stop

Or use an existing .perfetto-trace file.

2. Run an analysis

# Detect ANR events
perfetto-cli -t trace.perfetto-trace -p com.example.app anr detect

# Check frame performance
perfetto-cli -t trace.perfetto-trace -p com.example.app frame jank

# View CPU utilization
perfetto-cli -t trace.perfetto-trace -p com.example.app cpu utilization

3. Choose output format

# Human-friendly colored output (default)
perfetto-cli -t trace.perfetto-trace -p com.example.app frame jank

# ASCII table
perfetto-cli -t trace.perfetto-trace -p com.example.app frame jank -f table

# JSON for scripting
perfetto-cli -t trace.perfetto-trace -p com.example.app frame jank -f json

Global Options

Option Description
-t, --trace <path> Trace file path (required for analysis commands)
-p, --process <name> Process name filter
-f, --format <type> Output format: text / table / json (default: text)
-v, --verbose Verbose output
--tp-path <path> Custom trace_processor binary path
--version Show version

Next Steps