fallow inspect: all context for one file or export

Get all context for one file or export before you edit it: trace, dead code, duplication, complexity, security, and optional Fallow Cloud production data.

Before you edit a file or exported symbol, get all its evidence in one bundle with fallow inspect. The command is for agents that need the same context as the MCP inspect_target tool, without an MCP session.

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:

Evidence flags

Output

{
  "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": {} },
    "impact_closure": { "status": "ok", "scope": "project_filtered_to_file", "data": {} }
  },
  "warnings": []
}

Each evidence section has a status and a scope. The status is ok, partial (the type-aware backend reported incomplete coverage), unavailable (the analysis cannot run in this environment), or error. When one analysis in the bundle fails, and the failure is not fatal, fallow reports an error in that section and adds a warning. You can still use the rest of the bundle.

impact_closure uses the target file as the seed. It lists the files that a change to the target can affect. For a symbol target in type-aware mode, the bundle also has the semantic_trace, api_surface, symbol_impact, and targeted_tests sections.

inspect accepts the project and performance flags: --root, --config, --workspace, --production, --no-cache, and --threads. For the full list, see global flags.

Production data

With --cloud, fallow reads the production data of the file from Fallow Cloud and pairs it with the functions of the local file:

fallow inspect --file src/services/user.ts --cloud --format json --quiet

The key comes from $FALLOW_API_KEY, else from the key that fallow cloud login stored. The cloud section has its own status:

A status other than ok never fails the run. The static evidence stays complete.

{
  "status": "ok",
  "message": null,
  "repo": "acme/web",
  "latest_sha": "abc123",
  "period_days": 30,
  "summary": {
    "functions": 12, "called": 9, "never_called": 1, "untracked": 2,
    "calls": 48211, "error_groups": 1, "error_events": 7,
    "text": "12 functions: 9 ran, 1 never ran, 2 untracked."
  },
  "functions": [
    {
      "name": "loadUser", "line": 14, "stable_id": "fallow:fn:0f3a...",
      "match": "stable_id", "state": "called", "period_state": "called", "calls": 4120,
      "errors": { "groups": 1, "events": 7 },
      "cpu_ms_per_hour": 812.5, "browser_long_frame_ms_per_hour": null,
      "never_run_ranges": 2, "static_callers": 3,
      "production_callers": [
        { "stable_id": "fallow:fn:9c1e...", "file": "src/routes/user.ts", "function": "getUser", "line": 22, "samples": 140 }
      ],
      "summary": "loadUser ran 4,120 times."
    }
  ],
  "unpaired_local": [
    { "name": "newHelper", "line": 80, "note": "no production data (new or moved since deploy)" }
  ]
}

Fallow pairs each local function with a deployed function in two steps:

1. The stable_id: a hash of the file path, the function name, and the start line.
2. Else the name plus the position among the functions with the same name in the file. This step pairs a function that moved to another line. When the count of functions with that name changed, fallow does not pair them.

A local function without a pair goes to unpaired_local. It is new, or it moved in a way that fallow cannot follow. Fallow never pairs by name alone, because that gives the numbers of another function.

state is the state in the current deployment. period_state covers the whole period, earlier deployments included. A function with state: "never_called" and period_state: "called" did not run in this deployment, but it ran in an earlier one.

When the data of the file is not actionable yet, for example during the warm-up of a new deployment, Fallow Cloud withholds the never_called rows. The section message then says so, and each local function without a pair gets a note that it can still be deployed and tracked.

A null count means "not measured", never zero. For example, errors is null when error capture did not cover the function, and cpu_ms_per_hour is null without a CPU profile.

Each paired function also has these fields:

Compact output

--format compact prints one line per item, with or without --cloud:

fallow src/services/user.ts
finding unused-export src/services/user.ts:42 `formatUser` is never imported
finding complexity src/services/user.ts:14 loadUser cyclomatic 21 cognitive 30
prod loadUser:14 called 4120 calls, 1 error group (7 events), 812.5 ms CPU/h, 2 never-run branches, 3 static callers, prod callers getUser (src/routes/user.ts)
prod parseRow:60 never_called in 30 days
prod formatRow:72 not called in this deployment, called earlier in 30 days
prod newHelper:80 no production data (new or moved since deploy)

MCP parity

The MCP inspect_target tool uses the same CLI flow and returns the same JSON shape. When you already work in a shell or an editor command, use the CLI. When an agent is already connected to the MCP server, use MCP. Set cloud: true on a file target to add the cloud section. Set format: "compact" to get the compact text.

See also