A command-line interface for querying Firefox Profiler profiles with persistent daemon sessions.
npm install -g @firefox-devtools/profiler-cli@latestRequires Node.js >= 24.
profiler-cli load profile.json # Load a profile (file or https:// URL)
profiler-cli profile info # Show profile summary
profiler-cli thread info # List threads
profiler-cli thread select t-0 # Select a thread
profiler-cli thread samples # Show hot functions
profiler-cli stop # Stop the daemonprofiler-cli is also available as pq for shorter invocations (e.g. pq thread samples).
Run profiler-cli guide for a detailed usage guide with patterns and tips.
Run profiler-cli --help for the full options reference.
profiler-cli load <PATH> # Start daemon and load profile (file or http/https URL)
profiler-cli profile info # Print profile summary [--all] [--search <term>]
profiler-cli profile logs # Print Log markers in MOZ_LOG format [--thread] [--module] [--level] [--search] [--limit]
profiler-cli thread info # Print detailed thread information
profiler-cli thread select <handle> # Select a thread (e.g., t-0, t-1)
profiler-cli thread samples # Show hot functions list for current thread
profiler-cli thread samples-top-down # Show top-down call tree (where CPU time is spent)
profiler-cli thread samples-bottom-up # Show bottom-up call tree (what calls hot functions)
profiler-cli thread markers # List markers with aggregated statistics [--list for flat per-marker view]
profiler-cli thread functions # List all functions with CPU percentages
profiler-cli thread network # Show network requests with timing phases [--search] [--min-duration] [--max-duration] [--limit]
profiler-cli thread page-load # Show page load summary (navigation timing, resources, CPU, jank)
profiler-cli marker info <handle> # Show detailed marker information (e.g., m-1234)
profiler-cli marker stack <handle> # Show full stack trace for a marker
profiler-cli function expand <handle> # Show full untruncated function name (e.g., f-123)
profiler-cli function info <handle> # Show detailed function information
profiler-cli function annotate <handle> # Show annotated source/assembly with timing data [--mode src|asm|all] [--context 2|file|N] [--symbol-server <url>]
profiler-cli zoom push <range> # Push a zoom range (e.g., 2.7,3.1 or ts-g,ts-G or m-158)
profiler-cli zoom pop # Pop the most recent zoom range
profiler-cli zoom clear # Clear all zoom ranges (return to full profile)
profiler-cli filter push <filter-flag> # Push a sticky sample filter (see filter flags below)
profiler-cli filter pop [N] # Pop the last N filters (default: 1)
profiler-cli filter list # List active filters for current thread
profiler-cli filter clear # Remove all filters for current thread
profiler-cli status # Show session status (selected thread, zoom ranges, filters)
profiler-cli stop # Stop current daemon
profiler-cli stop <id> # Stop a specific session
profiler-cli stop --all # Stop all sessions
profiler-cli session list # List all running daemon sessions (* marks current)
profiler-cli session use <id> # Switch the current sessionprofiler-cli load <PATH> --session <id>
profiler-cli profile info --session <id>profiler-cli thread select t-93 # Select thread t-93
profiler-cli thread samples # View samples for selected thread
profiler-cli thread info --thread t-0 # View info for specific thread without selecting| Flag | Description |
|---|---|
--thread <handle> |
Specify thread (e.g., t-0) |
--search <term> |
Filter results by substring. For samples commands, comma-separates multiple terms that all must match (AND); | is literal, not OR. |
--include-idle |
Include idle samples (excluded by default in samples commands) |
--json |
Output as JSON (for use with jq, etc.) |
--limit <N> |
Limit number of results shown |
--max-lines <N> |
Limit call tree nodes for samples-top-down/samples-bottom-up (default: 100) |
--scoring <strategy> |
Call tree scoring: exponential-0.95, exponential-0.9 (default), exponential-0.8, harmonic-0.1, harmonic-0.5, harmonic-1.0, percentage-only |
--navigation <N> |
Select which navigation to show in thread page-load (1-based, default: last completed) |
--jank-limit <N> |
Max jank periods to show in thread page-load (default: 10, 0 = show all) |
--list |
Show a flat chronological list of individual markers (for thread markers) |
--all |
Show all threads in profile info (overrides default top-5 limit) |
--session <id> |
Use a specific session instead of the current one |
These work ephemerally on thread samples / thread functions, and as persistent filters via filter push.
| Flag | Description |
|---|---|
--excludes-function <f-N> |
Drop samples containing this function |
--merge <f-N,...> |
Remove functions from stacks (collapse them out) |
--root-at <f-N> |
Re-root stacks at this function |
--includes-function <f-N,...> |
Keep only samples containing any of these functions |
--includes-prefix <f-N,...> |
Keep only samples whose stack starts with this root-first sequence |
--includes-suffix <f-N> |
Keep only samples whose leaf frame is this function |
--during-marker --search <text> |
Keep only samples that fall during matching markers |
--outside-marker --search <text> |
Keep only samples that fall outside matching markers |
For filter push, exactly one flag per push. For ephemeral use, multiple flags may be combined and applied left-to-right; the same flag may also be repeated (e.g. --merge f-1 --merge f-2).
Sessions are stored in ~/.profiler-cli/ (or $PROFILER_CLI_SESSION_DIR to override).
See CONTRIBUTING.md for architecture, build instructions, and how to add new commands.