CLI Interface

Node.js command-line interface for opening speedscope with profile files in the browser. The CLI automatically detects profile formats, handles file reading, and launches the web interface with the profile data.

Capabilities

Command Line Usage

Primary CLI interface for launching speedscope with profile files.

# Open empty speedscope in browser
speedscope

# Open speedscope with a specific profile file
speedscope profile.json

# Read profile from stdin
cat profile.json | speedscope -
echo "profile_data" | speedscope -

# Show help information
speedscope --help
speedscope -h

# Show version information
speedscope --version
speedscope -v

CLI Arguments

The CLI accepts the following arguments and flags:

• No arguments: Opens empty speedscope in browser for manual file selection
• Single file path: Opens speedscope with the specified profile file
• - (dash): Reads profile data from stdin
• --help, -h: Shows help message and usage information
• --version, -v: Shows the current speedscope version

Internal CLI Functions

Core functions used internally by the CLI (not directly exposed for external use).

/**
 * Get readable stream from file path or stdin
 * @param relPath - Relative file path or '-' for stdin  
 * @returns Readable stream for the profile data
 */
function getProfileStream(relPath: string): NodeJS.ReadableStream;

/**
 * Read profile data into buffer from file or stdin
 * @param relPath - Relative file path or '-' for stdin
 * @returns Promise resolving to Buffer containing profile data
 */
function getProfileBuffer(relPath: string): Promise<Buffer>;

/**
 * Main CLI entry point with argument parsing and browser launching
 * Handles all CLI arguments and orchestrates the profile loading process
 * @returns Promise that resolves when CLI execution completes
 */
function main(): Promise<void>;

File Handling

The CLI automatically handles various file scenarios:

• Local files: Direct file system access with path resolution
• Stdin input: Reading from piped data or redirected input
• Large files: Automatic handling of files too large for browser URL parameters
• Binary files: Support for compressed and binary profile formats
• Cross-platform paths: Proper path handling on Windows, macOS, and Linux

Browser Integration

The CLI integrates with the system browser using the following approach:

1. Profile Processing: Converts profile data to base64 for browser transmission
2. Temporary Files: Creates temporary JavaScript files for large profiles
3. URL Generation: Constructs file:// URLs pointing to the speedscope web interface
4. Platform Handling: Special handling for macOS and Windows browser launch limitations
5. Hash Parameters: Uses URL hash fragments to pass profile data to the web interface

Usage Examples:

# Basic usage - open specific profile
speedscope cpu-profile.json

# Pipeline usage - process and view profile
some-profiler --output=json | speedscope -

# Multiple profile formats supported
speedscope trace.chrome.json          # Chrome DevTools
speedscope profile.stackprof.json     # Ruby stackprof  
speedscope callgrind.out.12345        # Callgrind format
speedscope profile.pb.gz              # Go pprof (compressed)

# Version and help
speedscope --version                  # Show version: v1.23.1
speedscope --help                     # Show usage help

Error Handling

The CLI provides comprehensive error handling for common scenarios:

• File not found: Clear error message when specified file doesn't exist
• Permission errors: Helpful message for files that can't be read
• Invalid formats: Graceful handling of unsupported profile formats
• Large files: Automatic fallback for files too large for URL parameters
• Browser launch failures: Error reporting when browser can't be opened

Cross-Platform Support

The CLI is designed to work across different operating systems:

• Windows: Proper handling of file paths and browser launching
• macOS: Workaround for browser URL hash parameter limitations
• Linux: Standard browser launching with full URL support
• File paths: Automatic path resolution and normalization

Temporary File Management

For large profiles that exceed URL parameter limits, the CLI:

1. Creates temporary JavaScript files in the system temp directory
2. Generates unique filenames to avoid conflicts
3. Creates redirect HTML files on platforms with browser limitations
4. Automatically cleans up temporary files (handled by OS)

The temporary file naming pattern: speedscope-{timestamp}-{pid}.js

Types

// CLI help string displayed with --help
const helpString: string;

// Main CLI function type
type MainFunction = () => Promise<void>;

// Profile processing function types
type GetProfileStream = (relPath: string) => NodeJS.ReadableStream;
type GetProfileBuffer = (relPath: string) => Promise<Buffer>;