> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fallow.tools/llms.txt
> Use this file to discover all available pages before exploring further.

# fallow trace

> CLI reference for fallow trace. Walk the callers and callees of one exported symbol through the module graph, bounded by depth. A standalone, best-effort symbol-level surface, separate from the ranked review brief.

Walk the symbol-level call chain for one exported symbol: callers **up** (modules that import the symbol) and callees **down** (import-symbol edges plus intra-module call sites), bounded by `--depth`. `trace` is its own surface for following how a symbol connects through the codebase before you change it.

```bash theme={null}
fallow trace src/api.ts:fetchUser --format json --quiet
fallow trace src/api.ts:fetchUser --callers --depth 2
```

<Note>
  `fallow trace` is a standalone, best-effort symbol-level surface. It is **not** folded into the ranked [review brief](/cli/audit#review-brief-and-decision-surface) and is never an input to the focus map or its ranking. Use it when you want to see how a symbol connects, not when you want a prioritized review.
</Note>

## Target

`fallow trace` takes one positional argument in `FILE:SYMBOL` form:

```bash theme={null}
fallow trace src/api.ts:fetchUser
```

`FILE` is a project-relative path and `SYMBOL` is the exported symbol name.

## Options

| Flag          | Description                                                                         |
| :------------ | :---------------------------------------------------------------------------------- |
| `--callers`   | Walk only the callers direction (modules that import the symbol).                   |
| `--callees`   | Walk only the callees direction (import-symbol edges plus intra-module call sites). |
| `--depth <N>` | Bound the walk depth in each requested direction.                                   |

When neither `--callers` nor `--callees` is set, both directions are walked.

## Common Flags

`trace` accepts the global project and performance flags:

| Flag                    | Description                                               |
| :---------------------- | :-------------------------------------------------------- |
| `-r, --root <PATH>`     | Project root directory.                                   |
| `-c, --config <PATH>`   | Path to a fallow config file.                             |
| `-f, --format <FORMAT>` | Output format: `human` (default) or `json`.               |
| `-q, --quiet`           | Suppress progress and status output on stderr.            |
| `--no-cache`            | Disable incremental parse cache.                          |
| `--threads <N>`         | Parser thread count.                                      |
| `--changed-since <REF>` | Scope file discovery to files changed since this git ref. |

## How it works

`trace` walks the module graph in two directions from the target symbol:

1. **Callers (up)**: the modules that import the symbol, followed up to `--depth` levels.
2. **Callees (down)**: the import-symbol edges out of the symbol's module plus the intra-module call sites, followed down to `--depth` levels.

The walk is best-effort and syntactic. Resolved and unresolved callees are reported honestly: an unresolved callee (for example, a dynamic call fallow cannot statically resolve) is surfaced as unresolved rather than silently dropped, so the chain reflects what fallow could and could not follow.

Because it is a standalone surface, `trace` never feeds the review brief's focus map or its ranking. The same best-effort call-chain data is available as opt-in evidence on [`fallow inspect --symbol-chain`](/cli/inspect#evidence-flags) and the `inspect_target` MCP tool's `symbol_chain` option.

## See also

<CardGroup cols={3}>
  <Card title="Inspect a target" icon="search-code" href="/cli/inspect">
    Compose one evidence bundle for a file or exported symbol, with opt-in `--symbol-chain`.
  </Card>

  <Card title="Audit and review brief" icon="terminal" href="/cli/audit">
    Changed-file verdict plus the graph-derived review brief and decision surface.
  </Card>

  <Card title="MCP integration" icon="robot" href="/integrations/mcp">
    Use fallow tools from AI coding agents.
  </Card>
</CardGroup>