0
# CLI Interface
1
2
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.
3
4
## Capabilities
5
6
### Command Line Usage
7
8
Primary CLI interface for launching speedscope with profile files.
9
10
```bash
11
# Open empty speedscope in browser
12
speedscope
13
14
# Open speedscope with a specific profile file
15
speedscope profile.json
16
17
# Read profile from stdin
18
cat profile.json | speedscope -
19
echo "profile_data" | speedscope -
20
21
# Show help information
22
speedscope --help
23
speedscope -h
24
25
# Show version information
26
speedscope --version
27
speedscope -v
28
```
29
30
### CLI Arguments
31
32
The CLI accepts the following arguments and flags:
33
34
- **No arguments**: Opens empty speedscope in browser for manual file selection
35
- **Single file path**: Opens speedscope with the specified profile file
36
- **`-` (dash)**: Reads profile data from stdin
37
- **`--help`, `-h`**: Shows help message and usage information
38
- **`--version`, `-v`**: Shows the current speedscope version
39
40
### Internal CLI Functions
41
42
Core functions used internally by the CLI (not directly exposed for external use).
43
44
```typescript { .api }
45
/**
46
* Get readable stream from file path or stdin
47
* @param relPath - Relative file path or '-' for stdin
48
* @returns Readable stream for the profile data
49
*/
50
function getProfileStream(relPath: string): NodeJS.ReadableStream;
51
52
/**
53
* Read profile data into buffer from file or stdin
54
* @param relPath - Relative file path or '-' for stdin
55
* @returns Promise resolving to Buffer containing profile data
56
*/
57
function getProfileBuffer(relPath: string): Promise<Buffer>;
58
59
/**
60
* Main CLI entry point with argument parsing and browser launching
61
* Handles all CLI arguments and orchestrates the profile loading process
62
* @returns Promise that resolves when CLI execution completes
63
*/
64
function main(): Promise<void>;
65
```
66
67
### File Handling
68
69
The CLI automatically handles various file scenarios:
70
71
- **Local files**: Direct file system access with path resolution
72
- **Stdin input**: Reading from piped data or redirected input
73
- **Large files**: Automatic handling of files too large for browser URL parameters
74
- **Binary files**: Support for compressed and binary profile formats
75
- **Cross-platform paths**: Proper path handling on Windows, macOS, and Linux
76
77
### Browser Integration
78
79
The CLI integrates with the system browser using the following approach:
80
81
1. **Profile Processing**: Converts profile data to base64 for browser transmission
82
2. **Temporary Files**: Creates temporary JavaScript files for large profiles
83
3. **URL Generation**: Constructs file:// URLs pointing to the speedscope web interface
84
4. **Platform Handling**: Special handling for macOS and Windows browser launch limitations
85
5. **Hash Parameters**: Uses URL hash fragments to pass profile data to the web interface
86
87
**Usage Examples:**
88
89
```bash
90
# Basic usage - open specific profile
91
speedscope cpu-profile.json
92
93
# Pipeline usage - process and view profile
94
some-profiler --output=json | speedscope -
95
96
# Multiple profile formats supported
97
speedscope trace.chrome.json # Chrome DevTools
98
speedscope profile.stackprof.json # Ruby stackprof
99
speedscope callgrind.out.12345 # Callgrind format
100
speedscope profile.pb.gz # Go pprof (compressed)
101
102
# Version and help
103
speedscope --version # Show version: v1.23.1
104
speedscope --help # Show usage help
105
```
106
107
### Error Handling
108
109
The CLI provides comprehensive error handling for common scenarios:
110
111
- **File not found**: Clear error message when specified file doesn't exist
112
- **Permission errors**: Helpful message for files that can't be read
113
- **Invalid formats**: Graceful handling of unsupported profile formats
114
- **Large files**: Automatic fallback for files too large for URL parameters
115
- **Browser launch failures**: Error reporting when browser can't be opened
116
117
### Cross-Platform Support
118
119
The CLI is designed to work across different operating systems:
120
121
- **Windows**: Proper handling of file paths and browser launching
122
- **macOS**: Workaround for browser URL hash parameter limitations
123
- **Linux**: Standard browser launching with full URL support
124
- **File paths**: Automatic path resolution and normalization
125
126
### Temporary File Management
127
128
For large profiles that exceed URL parameter limits, the CLI:
129
130
1. Creates temporary JavaScript files in the system temp directory
131
2. Generates unique filenames to avoid conflicts
132
3. Creates redirect HTML files on platforms with browser limitations
133
4. Automatically cleans up temporary files (handled by OS)
134
135
The temporary file naming pattern: `speedscope-{timestamp}-{pid}.js`
136
137
## Types
138
139
```typescript { .api }
140
// CLI help string displayed with --help
141
const helpString: string;
142
143
// Main CLI function type
144
type MainFunction = () => Promise<void>;
145
146
// Profile processing function types
147
type GetProfileStream = (relPath: string) => NodeJS.ReadableStream;
148
type GetProfileBuffer = (relPath: string) => Promise<Buffer>;
149
```