# Memray CLI Reference

## `memray run` — Capture Allocations

```bash
memray run [options] script.py [script_args...]
memray run [options] -m module [module_args...]
```

Output: `memray-<script>.<pid>.bin` by default.

### Core Flags

| Flag | Description |
|------|-------------|
| `-o, --output FILE` | Custom output filename |
| `-f, --force` | Overwrite existing output file |
| `-q, --quiet` | Suppress tracking output |
| `-c` | Execute program from string |
| `-m` | Run library module as script |

### Tracking Modes

| Flag | Description | Overhead |
|------|-------------|----------|
| `--native` | Capture C/C++ stack frames | Moderate |
| `--trace-python-allocators` | Record pymalloc allocations | High (larger files) |
| `--follow-fork` | Track child processes after fork | Creates separate files per child |
| `--live` | Launch live TUI immediately | N/A |
| `--live-remote` | Wait for `memray live <port>` client | N/A |
| `-p, --live-port PORT` | Port for live tracking (default: random) | N/A |

### Output Options

| Flag | Default | Description |
|------|---------|-------------|
| `--compress-on-exit` | True | Compress result with lz4 |
| `--no-compress` | False | Skip compression |
| `--aggregate` | False | Write aggregated stats instead of individual allocations |

### Caveats
- `--aggregate` cannot: detect temporary allocations, work with stats reporter, combine with live tracking
- `--native` requires report generation on the capture machine (shared library dependencies)
- `--follow-fork` incompatible with `--live` / `--live-remote`

---

## Reporters

All reporters take a `.bin` capture file as input.

### `memray flamegraph` — Interactive HTML Visualization

```bash
memray flamegraph [options] results.bin
```

| Flag | Description |
|------|-------------|
| `-o, --output FILE` | Output HTML filename |
| `-f, --force` | Overwrite existing file |
| `--temporal` | Dynamic flamegraph with time slider (~10ms granularity) |
| `--leaks` | Show unfreed memory instead of peak |
| `--temporary-allocations` | Show temporary allocations (threshold=1) |
| `--temporary-allocation-threshold N` | Custom threshold |
| `--split-threads` | Per-thread allocation view |
| `--inverted` | Invert parent-child (aggregate by function) |
| `--max-memory-records N` | Limit displayed records |
| `--no-web` | Use local assets instead of CDN |

**Reading flamegraphs:**
- Width = memory allocated by function + callees
- X-axis is NOT time
- Default icicle mode: root at top, allocations at bottom
- Flame mode: root at bottom (toggle in UI)
- Wide boxes at leaf = large direct allocations

**Temporal mode limitations:** Larger files, slower generation, incompatible with `--aggregate`

### `memray stats` — Terminal/JSON Statistics

```bash
memray stats [options] results.bin
```

| Flag | Description | Default |
|------|-------------|---------|
| `-n, --num-largest N` | Top N allocating functions | 5 |
| `--json` | Export as JSON file | |
| `-o, --output FILE` | JSON output filename | |
| `-f, --force` | Overwrite existing file | |

Shows: total allocations, total memory, size histogram, allocation type breakdown (MALLOC/CALLOC/MMAP), top functions by size and count.

**Cannot be used with aggregated capture files.**

### `memray table` — Sortable HTML Table

```bash
memray table [options] results.bin
```

| Flag | Description |
|------|-------------|
| `-o, --output FILE` | Output filename |
| `-f, --force` | Overwrite existing |
| `--leaks` | Show leaks instead of peak |
| `--temporary-allocations` | Show temporary allocations |
| `--temporary-allocation-threshold N` | Custom threshold |
| `--no-web` | Local assets |

Columns: Thread ID, Size, Allocator, Allocations count, Location (function:file:line)

### `memray summary` — Terminal Table

```bash
memray summary [options] results.bin
```

| Flag | Description | Default |
|------|-------------|---------|
| `-s, --sort-column N` | Sort by column N | 1 |
| `-r, --max-rows N` | Limit rows | |
| `--temporary-allocations` | Show temporary allocations |
| `--temporary-allocation-threshold N` | Custom threshold |

Columns: Own Memory (direct), Total Memory (including callees), Allocation Count

### `memray tree` — Interactive TUI

```bash
memray tree [options] results.bin
```

| Flag | Description | Default |
|------|-------------|---------|
| `-b, --biggest-allocs N` | Show N biggest allocations | 200 |
| `--temporary-allocations` | Show temporary allocations |
| `--temporary-allocation-threshold N` | Custom threshold |

**WARNING: Opens an interactive terminal application. Do NOT use in CI, automated scripts, or non-interactive contexts. Use `stats`, `summary`, or `flamegraph` instead.**

Controls: Arrow keys (navigate), `e` (expand), `i` (hide imports), `u` (show uninteresting)

### `memray live` — Real-Time TUI

```bash
# Start tracked program
memray run --live-remote script.py

# In another terminal, connect
memray live <port>
```

Controls: `t` (sort by total), `o` (sort by own), `a` (sort by count), `m` (toggle thread merge), `<`/`>` (switch threads)

**WARNING: Requires interactive terminal. Not for automation.**

---

## Typical Investigation Workflow

```bash
# 1. Capture with full detail
memray run --native --trace-python-allocators -o /tmp/investigate.bin my_script.py

# 2. Quick stats overview
memray stats /tmp/investigate.bin

# 3. Visual exploration
memray flamegraph /tmp/investigate.bin -o /tmp/flame.html

# 4. Check for leaks
memray flamegraph --leaks /tmp/investigate.bin -o /tmp/leaks.html

# 5. Find allocation churn
memray flamegraph --temporary-allocations /tmp/investigate.bin -o /tmp/temps.html

# 6. JSON export for scripting
memray stats --json -o /tmp/stats.json /tmp/investigate.bin
```
