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

> CLI reference for fallow inspect. Compose trace, dead-code, duplication, complexity, and security evidence for one file or exported symbol.

Compose one evidence bundle before editing a file or exported symbol. `inspect` is designed for agents that need the same context as the MCP `inspect_target` tool without starting an MCP session.

```bash theme={null}
fallow inspect --file src/api.ts --format json --quiet
fallow inspect --symbol src/api.ts:fetchUser --format json --quiet
```

## Target

Choose exactly one target form:

| Flag                     | Description                                                                                                                                                                |
| :----------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--file <PATH>`          | Inspect a project-relative file.                                                                                                                                           |
| `--symbol <FILE:EXPORT>` | Inspect one exported symbol, for example `src/api.ts:fetchUser`. Supporting dead-code, duplication, complexity, and security evidence is file-scoped in the first version. |

## Evidence flags

| Flag             | Description                                                                                                                                                                                                                               |
| :--------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--symbol-chain` | Also attach the best-effort symbol-level call chain (the same data as [`fallow trace`](/cli/trace)) as a `symbol_chain` evidence section. Only meaningful for a symbol target. Default off (best-effort, syntactic, off the ranked path). |

## Output

| Format  | Description                                                                                                                   |
| :------ | :---------------------------------------------------------------------------------------------------------------------------- |
| `human` | Compact target and identity summary.                                                                                          |
| `json`  | Machine-readable `kind: "inspect_target"` bundle with normalized target identity and evidence sections. Use this from agents. |

```json title="$ fallow inspect --file src/api.ts --format json --quiet" theme={null}
{
  "kind": "inspect_target",
  "target": {
    "type": "file",
    "file": "src/api.ts"
  },
  "identity": {
    "file": "src/api.ts",
    "is_reachable": true,
    "is_entry_point": false,
    "export_count": 3,
    "import_count": 2,
    "imported_by_count": 1
  },
  "evidence": {
    "trace_file": { "status": "ok", "scope": "file", "data": {} },
    "dead_code": { "status": "ok", "scope": "file", "data": {} },
    "duplication": { "status": "ok", "scope": "project_filtered_to_file", "data": {} },
    "complexity": { "status": "ok", "scope": "project_filtered_to_file", "data": {} },
    "security": { "status": "ok", "scope": "file", "data": {} }
  },
  "warnings": []
}
```

Each evidence section carries a `status` (`ok` or `error`) and `scope`. Non-fatal child-analysis failures are reported as section-level errors plus a warning, so the caller can still use the rest of the bundle.

## Common Flags

`inspect` accepts the global project and performance flags:

| Flag                         | Description                                                     |
| :--------------------------- | :-------------------------------------------------------------- |
| `-r, --root <PATH>`          | Project root directory.                                         |
| `-c, --config <PATH>`        | Path to a fallow config file.                                   |
| `-w, --workspace <PATTERNS>` | Scope analysis to selected workspace packages.                  |
| `--production`               | Apply production mode to trace, dead-code, and health evidence. |
| `--no-cache`                 | Disable incremental parse cache.                                |
| `--threads <N>`              | Parser thread count.                                            |

## MCP Parity

The MCP `inspect_target` tool uses the same CLI flow and returns the same JSON shape. Prefer the CLI when you are already in a shell or editor command, and MCP when an agent is already connected to the server.