> ## 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, or find the shortest import path between two modules. A standalone, best-effort 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
fallow trace --path src/app.ts src/db.ts
```

`--path` answers a different question from the symbol target: which chain of imports carries one module to another. See [Import path between two modules](#import-path-between-two-modules).

<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. Omit it when you pass `--path`, which takes two file paths instead.

## Options

| Flag                 | Description                                                                                                                                                               |
| :------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `--callers`          | Walk only the callers direction.                                                                                                                                          |
| `--callees`          | Walk only the callees direction.                                                                                                                                          |
| `--depth <N>`        | Bound the walk depth in each requested direction.                                                                                                                         |
| `--path <FROM> <TO>` | Find the shortest import path between two modules instead of walking a symbol. Mutually exclusive with the `FILE:SYMBOL` target, `--callers`, `--callees`, and `--depth`. |

When neither `--callers` nor `--callees` is set, both directions are walked. `trace` also accepts the project, output, and performance [global flags](/cli/global-flags) (`--root`, `--config`, `--format` with `human` or `json`, `--quiet`, `--no-cache`, `--threads`, `--changed-since`).

## How it works

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.

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.

## Import path between two modules

`fallow trace --path <FROM> <TO>` reports the shortest chain of imports by which `FROM` reaches `TO`. Both are project-relative file paths. Use it when you want to know how a module ends up depending on another one, rather than how a symbol is called.

Exact project-relative or absolute paths take priority over suffix matches. An abbreviation is accepted only when it identifies one module. A missing or ambiguous endpoint exits with code `2`; use the full project-relative path to disambiguate.

```bash title="$ fallow trace --path pages/report.tsx components/Box.tsx" theme={null}
Shortest import path (syntactic; OFF the ranked path)

  from: pages/report.tsx
  to:   components/Box.tsx
  hops: 3

  [1] pages/report.tsx:20 -> lib/related.transform.ts
  [2] lib/related.transform.ts:1 -> components/RelatedContent.tsx
  [3] components/RelatedContent.tsx:3 -> components/Box.tsx
```

JSON output carries the same walk under `kind: "trace"` with its own `schema_version`:

```json title="$ fallow trace --path pages/report.tsx components/Box.tsx --format json" theme={null}
{
  "kind": "trace",
  "schema_version": "1",
  "from": "pages/report.tsx",
  "to": "components/Box.tsx",
  "reachable": true,
  "hops": 3,
  "path": [
    {
      "from": "pages/report.tsx",
      "to": "lib/related.transform.ts",
      "type_only": false,
      "import_line": 20
    },
    {
      "from": "lib/related.transform.ts",
      "to": "components/RelatedContent.tsx",
      "type_only": false,
      "import_line": 1
    },
    {
      "from": "components/RelatedContent.tsx",
      "to": "components/Box.tsx",
      "type_only": false,
      "import_line": 3
    }
  ],
  "reason": "pages/report.tsx reaches components/Box.tsx in 3 hops"
}
```

Three behaviors are worth relying on. A type-only hop is reported with `type_only: true` rather than skipped, so a path that exists only in type space is visible instead of silently absent. An unreachable pair is a result, not an error: `reachable` is `false`, `path` is empty, `hops` is `0`, and `reason` says no import path was found. The command still exits `0`. And tracing a module to itself answers `reachable: true` with `hops: 0`, so branch on `reachable` rather than on the hop count, which is `0` in both cases.

## 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="Resolve a stack trace" icon="bug" href="/cli/trace-error">
    Map runtime stack-trace frames back to the definitions they name.
  </Card>

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