SDK overview

The nodehunter CLI is a thin host over @nodehunter/core — pure domain logic with no console.*, no process.*, and no Commander dependency. Use the SDK to embed scan, size, workspace analysis, and delete in scripts, CI, workers, or your own tools.

Install

SDK only (recommended for apps and libraries)

Install the dedicated core package when you import APIs in TypeScript or JavaScript:

npm install @nodehunter/core
# or: pnpm add @nodehunter/core

import { runScan, runSize, buildAnalysisCommandEnvelope } from '@nodehunter/core';

CLI package (terminal + nodehunter/core export)

Install nodehunter when you want the nodehunter binary. The published tarball is self-contained: dist/cli.js inlines the engine at build time (no runtime npm dependency on @nodehunter/core). The same release also exposes nodehunter/core — a separate SDK bundle from the same source:

npm install -g nodehunter

// Same engines — from the CLI tarball's core export (not @nodehunter/core on npm)
import { runScan } from 'nodehunter/core';

Goal	Install
Terminal commands only	nodehunter
Embed in your app / CI / service	@nodehunter/core (recommended for imports)
CLI binary + imports without a second registry package	nodehunter + import from 'nodehunter/core'

You typically do not install nodehunter and @nodehunter/core together unless you want the global binary plus a separately pinned SDK version in the same project.

Host contract

Core operations take a HostOperationContext built by your host:

Field	Host supplies
runtime.cwd	Working directory for reports
runtime.platform	resolveHostPlatform(process.platform) — never read inside core
scan	Path, depth, ignore, noDu, concurrency, …
list	--top / --full window
query	Package name, inspect focus
suggestions	createSuggestionHostContext(platform) for permission tips
session	createHostRunSession() for wall-clock timing

HostOperationContext
        ↓
runScan | runSize | runList | runFind | runWhy | runInspect | runDelete…
        ↓
{ analysis, output: HostCommandOutput }
        ↓
Your UI  ·  or  buildAnalysisCommandEnvelope()  ·  same shape as CLI --json

Operation entry points

API	Purpose
runScan	Read-only discovery
runSize	Physical disk sizing
runList / runFind / runWhy / runInspect	Workspace queries
runDeletePreview / runDeleteDeclined / runDeleteRefused / runDeleteExecute	Delete pipeline phases
buildWorkspaceIndex	Lower-level inventory without presentation lines

Subpath exports

Subpath	Stability	Purpose
@nodehunter/core	stable	Public SDK (runScan, runFind, envelopes, …)
@nodehunter/core/shared	stable	Scanner helpers and shared constants
@nodehunter/core/advanced	advanced	Low-level run emitters — pin versions; read release notes
@nodehunter/core/internal	internal	CLI host only — do not import in application code

Full guide: SDK exports and stability — tiers, upgrade reports, and the export governance README on GitHub.

Run pnpm exports:validate in the monorepo before releases.

Sizing in the SDK

Physical sizing uses the same provider resolution as the CLI:

• Prefer du -sb when the runtime probe succeeds
• Fall back to Node directory walk on Windows or when du is unavailable
• Force Node walk with scan.noDu: true (CLI: --no-du)

See Platforms and sizing.

Hooks

Hook	Use
onSizeNotice	Provider fallback or --no-du notices
onPerfDebug	Walk / size / wall timings
onWalkDebug	Skip reasons during traversal

Two size models (do not mix)

Model	APIs	Meaning
Physical	runSize, runList (projects), delete preview	On-disk node_modules bytes
Attributed	runFind, runWhy, list --package, some inspect focuses	Per-install attribution

JSON parity with the CLI

import { buildAnalysisCommandEnvelope } from '@nodehunter/core';

const { analysis, output } = await runSize(ctx);
const envelope = buildAnalysisCommandEnvelope({
  command: 'size',
  output,
  analysis,
});
// Same envelope as: nodehunter size . --json

Field reference: JSON output.

Examples (start here)

Runnable scripts live in examples/sdk/ in the repository — one file per core operation, shared fixtures, and delete safety gates.

SDK examples guide — full table, run commands, run* vs buildWorkspaceIndex, and how examples map to CLI hosts.

Quick run from a clone:

pnpm run core:build
pnpm tsx examples/sdk/scan/runScan.ts
pnpm tsx examples/sdk/size/runSize.ts

Safety for SDK hosts

• Core never prompts — hosts call runDeletePreview then confirm in UI before runDeleteExecute.
• Pass scan.path scoped narrowly.
• Use createSuggestionHostContext for platform-appropriate permission tips.

Related

• SDK examples
• SDK exports and stability
• Platforms and sizing
• JSON output
• Commands
• Workflows