0
# CLI Commands
1

2
Command-line interface for profiling applications and generating reports. Provides comprehensive tools for capturing profiles, generating visualizations, and analyzing memory usage patterns through terminal commands.
3

4
## Capabilities
5

6
### Profiling Commands
7

8
#### run
9

10
Execute Python scripts with memory tracking enabled.
11

12
```bash
13
memray run [options] script.py [script_args...]
14
```
15

16
Options:
17
- `--output FILE, -o FILE`: Output file for captured data (default: memray-{pid}.bin)
18
- `--live-remote`: Enable live remote monitoring
19
- `--live-port PORT`: Port for live monitoring (default: 12345)
20
- `--native`: Enable native stack traces
21
- `--follow-fork`: Continue tracking in forked processes
22
- `--trace-python-allocators`: Trace Python allocators separately
23
- `--quiet, -q`: Suppress output
24
- `--aggregate`: Use aggregated allocations format
25

26
Usage examples:
27

28
```bash
29
# Basic profiling
30
memray run --output profile.bin my_script.py
31

32
# With native traces and live monitoring
33
memray run --native --live-remote --live-port 8080 my_script.py
34

35
# Profile with arguments passed to script
36
memray run --output profile.bin my_script.py --input data.csv --verbose
37
```
38

39
#### attach
40

41
Attach to a running Python process for live profiling.
42

43
```bash
44
memray attach [options] pid
45
```
46

47
Options:
48
- `--output FILE, -o FILE`: Output file for captured data
49
- `--native`: Enable native stack traces
50
- `--duration SECONDS`: Duration to profile (default: indefinite)
51
- `--method METHOD`: Attachment method (default: auto)
52

53
Usage examples:
54

55
```bash
56
# Attach to process by PID
57
memray attach --output live_profile.bin 12345
58

59
# Attach for specific duration with native traces
60
memray attach --native --duration 60 --output short_profile.bin 12345
61
```
62

63
#### detach
64

65
Detach from a running Python process that was previously attached.
66

67
```bash
68
memray detach [options] pid
69
```
70

71
Usage example:
72

73
```bash
74
# Detach from process
75
memray detach 12345
76
```
77

78
### Report Generation Commands
79

80
#### flamegraph
81

82
Generate interactive HTML flame graphs from capture files.
83

84
```bash
85
memray flamegraph [options] capture_file.bin
86
```
87

88
Options:
89
- `--output FILE, -o FILE`: Output HTML file (default: memray-flamegraph-{pid}.html)
90
- `--leaks`: Show only leaked allocations
91
- `--temporary-allocations`: Show temporary allocations
92
- `--merge-threads`: Merge allocations across threads
93
- `--inverted`: Generate inverted flame graph
94
- `--temporal`: Show temporal allocation patterns
95

96
Usage examples:
97

98
```bash
99
# Basic flame graph
100
memray flamegraph profile.bin
101

102
# Focus on memory leaks
103
memray flamegraph --leaks --output leaks.html profile.bin
104

105
# Temporal flame graph with merged threads
106
memray flamegraph --temporal --merge-threads profile.bin
107
```
108

109
#### table
110

111
Generate interactive HTML table reports with sortable allocation data.
112

113
```bash
114
memray table [options] capture_file.bin
115
```
116

117
Options:
118
- `--output FILE, -o FILE`: Output HTML file (default: memray-table-{pid}.html)
119
- `--leaks`: Show only leaked allocations  
120
- `--temporary-allocations`: Show temporary allocations
121
- `--merge-threads`: Merge allocations across threads
122

123
Usage examples:
124

125
```bash
126
# Basic table report
127
memray table profile.bin
128

129
# Leaked allocations table
130
memray table --leaks --output leak_table.html profile.bin
131
```
132

133
#### tree
134

135
Generate text-based tree reports showing allocation hierarchies.
136

137
```bash
138
memray tree [options] capture_file.bin
139
```
140

141
Options:
142
- `--leaks`: Show only leaked allocations
143
- `--temporary-allocations`: Show temporary allocations  
144
- `--merge-threads`: Merge allocations across threads
145
- `--biggest-allocs N`: Show N biggest allocations (default: 10)
146

147
Usage examples:
148

149
```bash
150
# Basic tree report  
151
memray tree profile.bin
152

153
# Show top 20 leaked allocations
154
memray tree --leaks --biggest-allocs 20 profile.bin
155
```
156

157
### Analysis Commands
158

159
#### summary
160

161
Generate summary statistics from capture files.
162

163
```bash
164
memray summary [options] capture_file.bin
165
```
166

167
Options:
168
- `--json`: Output in JSON format
169
- `--merge-threads`: Merge statistics across threads
170

171
Usage examples:
172

173
```bash
174
# Text summary
175
memray summary profile.bin
176

177
# JSON output for scripting
178
memray summary --json profile.bin > summary.json
179
```
180

181
#### stats
182

183
Generate detailed statistics and allocation breakdowns.
184

185
```bash
186
memray stats [options] capture_file.bin
187
```
188

189
Options:
190
- `--json`: Output in JSON format
191
- `--merge-threads`: Merge statistics across threads
192

193
Usage example:
194

195
```bash
196
# Detailed statistics
197
memray stats profile.bin
198
```
199

200
#### parse
201

202
Parse and extract raw data from capture files.
203

204
```bash
205
memray parse [options] capture_file.bin
206
```
207

208
Options:
209
- `--output FILE, -o FILE`: Output file for parsed data
210
- `--format FORMAT`: Output format (json, csv)
211

212
Usage example:
213

214
```bash
215
# Extract to JSON
216
memray parse --format json --output data.json profile.bin
217
```
218

219
### Live Monitoring Commands
220

221
#### live
222

223
Connect to and monitor live profiling sessions.
224

225
```bash
226
memray live [options] port
227
```
228

229
Options:
230
- `--refresh-rate SECONDS`: Update interval (default: 1)
231
- `--merge-threads`: Merge allocations across threads
232

233
Usage examples:
234

235
```bash
236
# Monitor live session
237
memray live 12345
238

239
# Monitor with custom refresh rate
240
memray live --refresh-rate 0.5 12345
241
```
242

243
### File Transformation Commands
244

245
#### transform
246

247
Transform capture files between different formats.
248

249
```bash
250
memray transform [options] input_file.bin output_file.bin
251
```
252

253
Options:
254
- `--format FORMAT`: Target format (all_allocations, aggregated_allocations)
255

256
Usage example:
257

258
```bash
259
# Convert to aggregated format
260
memray transform --format aggregated_allocations profile.bin profile_agg.bin
261
```
262

263
## Global Options
264

265
Most commands support these global options:
266

267
- `--help, -h`: Show command help
268
- `--version`: Show memray version  
269
- `--verbose, -v`: Verbose output
270
- `--quiet, -q`: Suppress non-error output
271

272
## Integration Examples
273

274
### Continuous Integration
275

276
```bash
277
#!/bin/bash
278
# CI script for memory profiling
279

280
# Run tests with profiling
281
memray run --output ci_profile.bin -m pytest tests/
282

283
# Generate reports
284
memray flamegraph --output reports/flamegraph.html ci_profile.bin
285
memray summary --json ci_profile.bin > reports/summary.json
286

287
# Check for memory leaks
288
if memray tree --leaks ci_profile.bin | grep -q "Leaked"; then
289
    echo "Memory leaks detected!"
290
    exit 1
291
fi
292
```
293

294
### Development Workflow
295

296
```bash
297
# Profile during development
298
memray run --live-remote --live-port 8080 my_app.py &
299
APP_PID=$!
300

301
# Monitor in another terminal
302
memray live 8080
303

304
# Generate reports after stopping
305
memray flamegraph memray-${APP_PID}.bin
306
memray table memray-${APP_PID}.bin
307
```