or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

cli.md index.md programmatic-api.md

tile.json

Command Line Interface

Comprehensive CLI tool providing single-command profiling with extensive configuration options for development and production use cases.

Capabilities

Basic Command Structure

The 0x CLI follows a standard pattern with optional flags followed by the target Node.js command.

# Basic command structure
0x [flags] -- node [nodeFlags] script.js [scriptFlags]

# Simple profiling (uses default node)
0x [flags] script.js [scriptFlags]

Basic Usage Examples:

# Profile a script
0x my-app.js

# Profile with specific Node.js flags
0x -- node --max-old-space-size=4096 my-app.js

# Profile Express server
0x server.js

# Profile with script arguments
0x -- node server.js --port 8080 --env production

Output Control Flags

Control where and how profiling output is generated and displayed.

# Output directory control
-D, --output-dir DIR        # Output directory pattern (default: {pid}.0x)
-F, --output-html FILE      # Output HTML file pattern

# Browser control  
-o, --open                  # Open flamegraph in browser automatically

# Naming and titles
--name NAME                 # Output name prefix (default: flamegraph)  
--title TITLE               # Flamegraph title

Output Examples:

# Custom output location
0x -D ./profiles/{name}-{timestamp} my-app.js

# Custom HTML file with auto-open
0x -F ./reports/profile-{pid}.html -o my-app.js

# Named profile with title
0x --name "api-performance" --title "API Server Profile" server.js

Profiling Mode Flags

Control what type of profiling is performed and how data is processed.

# Collection modes
--collect-only              # Only collect data, don't generate flamegraph
--collect-delay MS          # Delay before starting collection (milliseconds)

# Visualization modes  
--visualize-only DIR        # Visualize existing profiling data folder
--visualize-cpu-profile FILE # Visualize existing V8 CPU profile

# Platform options
--kernel-tracing            # Use Linux kernel tracing (requires sudo)
--path-to-node-binary PATH  # Custom Node.js binary path

Mode Examples:

# Collect data for later analysis
0x --collect-only --output-dir ./data/{timestamp} my-app.js

# Visualize previously collected data
0x --visualize-only ./1234.0x --open

# Linux kernel tracing for native stack visibility
sudo 0x --kernel-tracing my-app.js

# Delayed profiling start (useful for initialization)
0x --collect-delay 5000 my-app.js

Load Testing Integration

Automatically execute load testing commands when the profiled application opens a port.

-P, --on-port CMD           # Command to run when port is detected

The $PORT variable is automatically substituted with the detected port number.

Load Testing Examples:

# Basic load testing with autocannon
0x -P 'autocannon localhost:$PORT' server.js

# Custom load testing with curl
0x -P 'curl -X POST localhost:$PORT/api/data' api-server.js

# Artillery load testing
0x -P 'artillery quick --count 100 --num 10 localhost:$PORT' server.js

# Multiple commands  
0x -P 'sleep 2 && autocannon -c 100 -d 30 localhost:$PORT' server.js

Debug and Development Flags

Additional flags for debugging profiling issues and development workflows.

# Debug output
-q, --quiet                 # Suppress status messages
-s, --silent                # Silent mode (no output)
--tree-debug                # Generate debug tree data file
--write-ticks               # Write raw tick data to file

# Kernel tracing debug (Linux only)
--kernel-tracing-debug      # Enable debug output for kernel tracing

Debug Examples:

# Generate debug data files
0x --tree-debug --write-ticks my-app.js

# Silent profiling for scripts
0x --silent --collect-only automated-test.js

# Kernel tracing with debug output
sudo 0x --kernel-tracing --kernel-tracing-debug my-app.js

Help and Version

Standard CLI help and version information.

-h, --help                  # Show help information and usage
-v, --version               # Show version number

Template Variables in Paths

Output directory and HTML file patterns support template variable substitution:

# Available template variables
{pid}         # Process ID of profiled application
{timestamp}   # Timestamp when profiling started  
{cwd}         # Current working directory
{name}        # Name specified with --name flag
{outputDir}   # Output directory path (for HTML files)

Template Examples:

# Timestamped directories
0x -D "./profiles/{name}-{timestamp}" --name "server" my-app.js

# PID-based HTML files  
0x -F "./reports/profile-{pid}-{timestamp}.html" my-app.js

# Organized output structure
0x -D "./{name}/{timestamp}" -F "{outputDir}/flamegraph.html" --name "api" server.js

Platform-Specific Considerations

Linux Kernel Tracing

Enhanced profiling on Linux systems using perf for native stack visibility:

# Requires sudo access
sudo 0x --kernel-tracing my-app.js

# Check sudo access first
sudo -v && 0x --kernel-tracing my-app.js

# Kernel tracing with debug output
sudo 0x --kernel-tracing --kernel-tracing-debug my-app.js

Note: Kernel tracing cannot be used with --on-port flag. Run load testing in a separate terminal.

Cross-Platform Compatibility

V8 profiling works on all platforms where Node.js runs:

# Works on macOS, Linux, Windows, Android, etc.
0x my-app.js

# Custom Node.js binary (any platform)
0x --path-to-node-binary /custom/path/to/node my-app.js

Complete Flag Reference

Boolean Flags

-o, --open                    # Open flamegraph in browser
-q, --quiet                   # Suppress status messages  
-s, --silent                  # Silent mode
-h, --help                    # Show help
-v, --version                 # Show version
--collect-only                # Only collect data
--kernel-tracing              # Use Linux kernel tracing
--kernel-tracing-debug        # Kernel tracing debug output
--tree-debug                  # Generate debug tree data
--write-ticks                 # Write raw tick data

String/Value Flags

-D, --output-dir DIR          # Output directory pattern
-F, --output-html FILE        # Output HTML file pattern
-P, --on-port CMD             # Command for port detection
--working-dir DIR             # Working directory
--name NAME                   # Output name prefix  
--title TITLE                 # Flamegraph title
--visualize-only DIR          # Visualize existing data
--visualize-cpu-profile FILE  # Visualize CPU profile
--collect-delay MS            # Collection delay (milliseconds)
--path-to-node-binary PATH    # Custom Node.js binary

Exit Codes and Signals

The 0x CLI handles signals and exit codes appropriately:

# Signal handling
SIGINT (Ctrl+C)    # Gracefully stops profiling and generates flamegraph
SIGTERM           # Gracefully stops profiling and generates flamegraph

# Exit codes
0                 # Success - flamegraph generated
1                 # Error - check error output for details

Advanced CLI Patterns

Production Server Profiling

# Collect data in production environment
0x --collect-only --silent \
   -D "/var/log/profiles/{name}-{timestamp}" \
   --name "production-api" \
   --collect-delay 10000 \
   server.js

# Later: generate flamegraph from collected data
0x --visualize-only /var/log/profiles/production-api-1234567890 \
   --title "Production API Profile" \
   -F "/var/www/html/flamegraphs/latest.html"

Automated Performance Testing

#!/bin/bash
# Script for automated performance profiling

# Start profiling with load test
0x --collect-only \
   -P "autocannon -c 50 -d 60 localhost:$PORT/api/benchmark" \
   -D "./perf-data/{timestamp}" \
   --name "benchmark-$(date +%Y%m%d)" \
   server.js

# Generate flamegraph from data
0x --visualize-only "./perf-data/$(ls -t perf-data/ | head -1)" \
   --title "Benchmark Results $(date)" \
   -F "./reports/benchmark-$(date +%Y%m%d).html" \
   --open

Development Workflow Integration

# Quick development profiling
alias profile='0x --open --name "dev-profile"'
alias profile-debug='0x --tree-debug --write-ticks --open'

# Use in development  
profile my-app.js
profile-debug problem-script.js