> ## 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.

When the same export is referenced in both type and value space, JSON output adds `direct_references_by_namespace` with separate evidence for each lane. `namespace` and `direct_references` keep their existing winning-lane meaning for compatibility. The grouped field is omitted when only one lane has references, so consumers should treat its absence as the common single-namespace case.

## Ambiguous star exports

When two `export *` sources contribute the requested name, the barrel exports
nothing under that name. JSON output reports `symbol_found: false` and adds a
`star_export_ambiguity` object:

```json theme={null}
{
  "symbol_found": false,
  "star_export_ambiguity": {
    "sources": ["src/models/admin.ts", "src/models/customer.ts"],
    "namespaces": ["type"]
  }
}
```

`sources` contains the sorted project-relative declaration origins.
`namespaces` identifies whether the collision is in type space, value space,
or both, with `type` before `value`. This field distinguishes a barrel
collision from an unknown or misspelled symbol. Keep one origin, rename the
others, or replace the star exports with explicit re-exports.

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>