# CLI Reference

Full command reference for the `llmdebug` CLI. For a quick overview, see the
[README](../README.md#cli).

Requires the `cli` extra: `pip install llmdebug[cli]`

## Commands

### show

Display a snapshot with configurable detail level.

```bash
llmdebug                                # Latest snapshot (crash-level detail)
llmdebug show                           # Same as above
llmdebug show previous                  # Second most recent snapshot
llmdebug show --detail full             # All stack frames
llmdebug show --detail context          # Everything (pytest/env/capture context)
llmdebug show --json                    # Crash-level JSON
llmdebug show --json --detail context   # Expanded JSON with full context
llmdebug show --raw-session             # Output raw DebugSession envelope JSON
```

JSON output (`--json`) returns the raw snapshot payload for programmatic
consumption or piping to other tools.

### list

List recent snapshots with metadata.

```bash
llmdebug list                           # List all snapshots
```

### frames

Inspect a specific stack frame from a snapshot.

```bash
llmdebug frames -i 0                    # Crash frame from latest snapshot
llmdebug frames previous -i 0           # Crash frame from previous snapshot
llmdebug frames '#3' -i 2               # Frame 2 from snapshot #3
```

### diff

Compare two snapshots to see what changed between runs.

```bash
llmdebug diff                           # Compare latest vs previous
llmdebug diff #2 #1                     # Compare numbered entries from `llmdebug list`
llmdebug diff old.json new.json         # Compare specific files
llmdebug diff --json                    # Output diff as JSON
```

### git-context

Get richer git-aware debugging metadata on demand (without inflating snapshot
capture payloads).

```bash
llmdebug git-context                    # Latest snapshot, text view
llmdebug git-context --json             # JSON output for tooling
llmdebug git-context '#2'               # Specific snapshot reference
```

Outputs metadata only:
- Crash-line blame metadata
- Recent commit metadata + shortstats
- Crash-file diffstat metadata

### clean

Remove old snapshots, keeping only the most recent.

```bash
llmdebug clean -k 5                     # Keep only 5 most recent snapshots
```

## Detail Levels

The `show` command defaults to **crash** level to keep evidence compact.
Expand to `full` or `context` only when the extra state is needed:

| Level | Content | Typical Size |
|-------|---------|--------------|
| `crash` (default) | Exception + crash frame only | ~2K tokens |
| `full` | All frames + traceback | ~5K tokens |
| `context` | Everything (repro, git, env, coverage) | ~10K tokens |

## Snapshot References

All inspection commands share one reference syntax:

| Reference | Meaning |
|-----------|---------|
| `latest` or no argument | Most recent snapshot |
| `previous` | Second most recent snapshot |
| `#N` | Numbered entry from `llmdebug list` (1-based) |
| file path | Load a specific snapshot file directly |

All commands accept `--dir <path>` to point at a custom snapshot directory.

## Common Workflows

### First failure

```bash
pytest                                  # Failure creates snapshot
llmdebug                                # Read crash summary
llmdebug show --detail context          # Get full context if needed
```

### Compare before/after a fix attempt

```bash
pytest                                  # Second failure creates new snapshot
llmdebug diff                           # See what changed
```

### Deep frame inspection

```bash
llmdebug show --detail full             # See all frames
llmdebug frames -i 2                    # Zoom into a specific frame
llmdebug git-context                    # Check blame/diff for crash file
```
