# lpm graph (/docs/packages/graph)



```bash
lpm graph [package] [--format <FMT>] [filters...]
```

Renders the project's dependency graph in one of six formats. With no `package` argument, shows the entire installed tree from the root; with a package name, shows just that subtree.

## Examples [#examples]

```bash
lpm graph                              # full tree, terminal output
lpm graph react                        # subtree under react
lpm graph --format mermaid             # Mermaid for embedding in markdown
lpm graph --format dot > graph.dot     # GraphViz, pipe into `dot`
lpm graph --format html                # writes .lpm/graph.html, opens in browser
lpm graph --format html --no-open      # write the file but don't open it (CI-safe)
lpm graph --format json                # structured for tooling
lpm graph --format stats               # counts and aggregates only
lpm graph --why lodash                 # why is lodash in the tree?
lpm graph --depth 3                    # truncate tree at depth 3
lpm graph --filter react               # only subtrees whose package names contain 'react'
lpm graph --filter press               # substring match: keeps the express branch
lpm graph --prod                       # production deps only
lpm graph --dev                        # devDependencies only
```

## Output formats [#output-formats]

| Format           | Output destination                                                                                           | Best for                                            |
| ---------------- | ------------------------------------------------------------------------------------------------------------ | --------------------------------------------------- |
| `tree` (default) | stdout — indented terminal tree of resolved `name@version` nodes                                             | Quick eyeballing                                    |
| `dot`            | stdout — GraphViz DOT source                                                                                 | Pipe into `dot -Tpng > graph.png`                   |
| `mermaid`        | stdout — Mermaid graph block                                                                                 | Embedding in markdown / docs                        |
| `json`           | stdout — structured graph data                                                                               | Tooling, custom analyses                            |
| `stats`          | stdout — counts (total deps, max depth, duplicates)                                                          | High-level audits                                   |
| `html`           | **writes** `<project>/.lpm/graph.html` and auto-opens it in your default browser (suppress with `--no-open`) | Interactive exploration, sharing with non-CLI users |

The `html` format is the only one that writes to disk — every other format prints to stdout so you can pipe or redirect it. Pair `--format html` with `--no-open` in headless / CI environments where opening a browser would either fail or be unwanted.

## `--why <package>` [#--why-package]

```bash
lpm graph --why lodash
```

Walks every path from the root to the named package and prints them. Useful for "why am I shipping this" investigations and for hunting down a transitive bump that pulled in something unexpected.

## Filtering [#filtering]

`--depth`, `--filter`, `--prod`, and `--dev` are applied at the graph level — every output format (tree, dot, mermaid, json, stats, html) sees the same truncated set, including the stats summary embedded in the HTML header.

| Flag              | Effect                                                                                                                                                                                                |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--depth <N>`     | Truncate the graph at depth N (root counts as level 1, direct deps as level 2). `--depth 1` keeps just the root, `--depth 2` keeps root + direct deps, `--depth 3` keeps one transitive layer beyond. |
| `--filter <NAME>` | Only show subtrees that contain this substring in a package name. Diamond patterns (two parents to the same target) keep both branches.                                                               |
| `--prod`          | Production dependencies only (mutually exclusive with `--dev`)                                                                                                                                        |
| `--dev`           | devDependencies only                                                                                                                                                                                  |

## Flags [#flags]

| Flag              | Effect                                                                                                                                                                                                                                                      |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--format <FMT>`  | One of `tree`, `dot`, `mermaid`, `json`, `stats`, `html` (default: `tree`)                                                                                                                                                                                  |
| `--why <PKG>`     | Show every path from the root to `<PKG>`                                                                                                                                                                                                                    |
| `--depth <N>`     | Truncate the graph at depth N (applied to every format)                                                                                                                                                                                                     |
| `--filter <NAME>` | Only subtrees containing this substring in a package name                                                                                                                                                                                                   |
| `--prod`          | Production deps only                                                                                                                                                                                                                                        |
| `--dev`           | devDependencies only                                                                                                                                                                                                                                        |
| `--no-open`       | With `--format html`: write the file but skip the auto-open call. Useful in headless / CI environments. Used without `--format html`, prints a one-line warning that the flag has no effect in human mode; the warning is suppressed under global `--json`. |

Plus the [global flags](/docs/commands#global-flags).

## See also [#see-also]

* [`lpm query`](/docs/packages/query) — selector-based queries against installed packages
* [`lpm audit`](/docs/packages/audit) — security and quality audit
* [Dependency graph](/docs/infra/dependency-graph) — design overview