0
# CLI Interface
1

2
Command-line interface for metro-symbolicate supporting multiple input formats and symbolication options.
3

4
## Capabilities
5

6
### Stack Trace Symbolication from Stdin
7

8
Reads stack traces from standard input and symbolicates them using the provided source map.
9

10
```bash { .api }
11
metro-symbolicate <source-map-file>
12
```
13

14
**Usage Examples:**
15

16
```bash
17
# Symbolicate stack trace from file
18
cat error-stack-trace.txt | metro-symbolicate bundle.js.map
19

20
# Symbolicate stack trace piped from another command
21
node app.js 2>&1 | metro-symbolicate bundle.js.map
22

23
# With function name options
24
cat stack.txt | metro-symbolicate bundle.js.map --no-function-names
25
```
26

27
### Explicit Coordinate Symbolication
28

29
Symbolicates specific line and column coordinates in the bundled code.
30

31
```bash { .api }
32
metro-symbolicate <source-map-file> <line> [column]
33
```
34

35
**Parameters:**
36
- `line` - Line number in the bundled code (1-based by default)
37
- `column` - Column number in the bundled code (0-based by default, optional)
38

39
**Usage Examples:**
40

41
```bash
42
# Symbolicate line 42, column 15
43
metro-symbolicate bundle.js.map 42 15
44

45
# Symbolicate line 100, column defaults to 0
46
metro-symbolicate bundle.js.map 100
47

48
# With custom line/column start offsets
49
metro-symbolicate bundle.js.map 42 15 --input-line-start 0 --input-column-start 1
50
```
51

52
### Module ID Symbolication
53

54
Symbolicates coordinates within a specific module in segmented bundles (e.g., RAM bundles).
55

56
```bash { .api }
57
metro-symbolicate <source-map-file> <moduleId>.js <line> [column]
58
```
59

60
**Parameters:**
61
- `moduleId` - Module identifier followed by `.js`
62
- `line` - Line number within the module
63
- `column` - Column number within the module (optional)
64

65
**Usage Examples:**
66

67
```bash
68
# Symbolicate line 10 in module 123
69
metro-symbolicate bundle.js.map 123.js 10
70

71
# Symbolicate line 10, column 5 in module 456
72
metro-symbolicate bundle.js.map 456.js 10 5
73
```
74

75
### Profiler Map Symbolication
76

77
Symbolicates React Native profiler maps (.profmap files).
78

79
```bash { .api }
80
metro-symbolicate <source-map-file> <file>.profmap
81
```
82

83
**Usage Examples:**
84

85
```bash
86
# Symbolicate profiler map
87
metro-symbolicate bundle.js.map trace.profmap > symbolicated-trace.profmap
88

89
# Process profiler data from React Native
90
metro-symbolicate index.android.bundle.map profile-12345.profmap
91
```
92

93
### CPU Profile Symbolication
94

95
Symbolicates Chrome DevTools CPU profiles (.cpuprofile files).
96

97
```bash { .api }
98
metro-symbolicate <source-map-file> <file>.cpuprofile
99
```
100

101
**Usage Examples:**
102

103
```bash
104
# Symbolicate CPU profile
105
metro-symbolicate bundle.js.map cpu-profile.cpuprofile
106

107
# Process Chrome DevTools performance data
108
metro-symbolicate app.js.map performance-profile.cpuprofile
109
```
110

111
### Heap Snapshot Symbolication
112

113
Symbolicates Chrome DevTools heap snapshots and heap timelines.
114

115
```bash { .api }
116
metro-symbolicate <source-map-file> <file>.heapsnapshot
117
metro-symbolicate <source-map-file> <file>.heaptimeline
118
```
119

120
**Usage Examples:**
121

122
```bash
123
# Symbolicate heap snapshot
124
metro-symbolicate bundle.js.map heap-snapshot.heapsnapshot > symbolicated.json
125

126
# Symbolicate heap timeline
127
metro-symbolicate bundle.js.map allocation-timeline.heaptimeline > timeline.json
128
```
129

130
### Attribution File Processing
131

132
Processes JSONL attribution files for bundle size analysis.
133

134
```bash { .api }
135
metro-symbolicate <source-map-file> --attribution < input.jsonl > output.jsonl
136
```
137

138
**Usage Examples:**
139

140
```bash
141
# Process bundle attribution data
142
metro-symbolicate bundle.js.map --attribution < bundle-sizes.jsonl > attributed-sizes.jsonl
143

144
# Chain with bundle analysis tools
145
analyze-bundle bundle.js | metro-symbolicate bundle.js.map --attribution > results.jsonl
146
```
147

148
### Hermes Integration
149

150
Special modes for processing Hermes JavaScript engine crash dumps and coverage traces.
151

152
```bash { .api }
153
metro-symbolicate <source-map-file> --hermes-crash
154
metro-symbolicate <source-map-file> --hermes-coverage
155
```
156

157
**Hermes Crash Mode:**
158
Processes Hermes crash dump JSON from stdin and outputs symbolicated stack traces.
159

160
```bash
161
cat hermes-crash.json | metro-symbolicate bundle.js.map --hermes-crash
162
```
163

164
**Hermes Coverage Mode:**
165
Processes Hermes coverage trace JSON from stdin for code coverage analysis.
166

167
```bash
168
cat coverage-trace.json | metro-symbolicate bundle.js.map --hermes-coverage
169
```
170

171
## CLI Options
172

173
### Function Name Options
174

175
```bash { .api }
176
--no-function-names
177
```
178

179
Use identifier names instead of function names in symbolicated output. By default, metro-symbolicate attempts to use function names from source map metadata.
180

181
### Hermes Options
182

183
```bash { .api }
184
--hermes-crash
185
--hermes-coverage
186
```
187

188
Special processing modes for Hermes JavaScript engine. These options are mutually exclusive.
189

190
- `--hermes-crash`: Process Hermes minidump crash information
191
- `--hermes-coverage`: Process Hermes code coverage traces
192

193
### Line and Column Offset Options
194

195
Control how line and column numbers are interpreted and displayed.
196

197
```bash { .api }
198
--input-line-start <number>     # Default: 1
199
--input-column-start <number>   # Default: 0
200
--output-line-start <number>    # Default: 1
201
--output-column-start <number>  # Default: 0
202
```
203

204
**Usage Examples:**
205

206
```bash
207
# 0-based input, 1-based output (common for some tools)
208
metro-symbolicate bundle.js.map 0 5 --input-line-start 0 --output-line-start 1
209

210
# All 1-based numbering
211
metro-symbolicate bundle.js.map 1 6 --input-line-start 1 --input-column-start 1
212
```
213

214
## Directory-based Source Maps
215

216
Metro-symbolicate can work with directories containing multiple source map files instead of a single source map file.
217

218
```bash { .api }
219
metro-symbolicate <source-map-directory>/
220
```
221

222
**Usage Examples:**
223

224
```bash
225
# Use directory of source maps
226
metro-symbolicate ./source-maps/ 42 15
227

228
# Process stack trace with directory
229
cat stack.txt | metro-symbolicate ./maps/
230
```
231

232
## Error Handling
233

234
The CLI returns appropriate exit codes:
235
- `0`: Success
236
- `1`: Error (invalid arguments, file not found, parsing errors, etc.)
237

238
Common error scenarios:
239
- Invalid source map file or directory
240
- Malformed stack traces or input data
241
- Conflicting command-line options (e.g., `--hermes-crash` with `--hermes-coverage`)
242
- Missing required arguments