Commands & Options

Complete reference for all npkill CLI flags and options.

Basic Usage

npx npkill [options]

Options Reference

Flag Description Default
-d, --directory <path> Set the directory from which to begin searching . (current)
-f, --full Start searching from the user's home directory false
-p, --profiles [names] Profiles to search with, separated by commas (e.g., -p python,java). all uses every profile. Without a value, lists the available profiles node
-t, --targets <names> Search for these directory names instead of using profiles (comma-separated). Can't be combined with -p —
-s, --sort <type> Sort results by: size, path, or age none
-E, --exclude <patterns> Skip matching directories and their contents (comma-separated). name matches at any depth, ./name or parent/name from the scan root, **/parent/name at any depth, and an absolute path matches exactly —
--include-sensitive Show sensitive results too, like the dependencies some apps need to run false
--no-ignore-default Also look inside the folders skipped by default, like .git or .nvm false
--older-than <days> Only show results whose project has not been modified in more than the given number of days —
-D, --delete-all Automatically delete all found directories. Requires --targets. Add -y and --json or --json-stream to delete without the interface (use with caution!) false
-y Skip the warning shown by --delete-all false
--dry-run Simulate deletion without actually deleting anything false
-e, --hide-errors Hide error messages false
--size-unit <unit> Size display unit: auto, mb or gb. With auto, sizes under 1024 MB are shown in MB and larger ones in GB auto
--no-size Skip size calculation. Faster scans and deletions when you don't need sizes false
--no-age Skip age (last modification time) calculation false
--no-stats Skip both size and age calculation. Same as --no-size --no-age false
--json Print all results as a single JSON object at the end of the scan false
--json-stream Print each result as a JSON object on its own line false
--config <path> Path to custom .npkillrc config file ./.npkillrc, then ~/.npkillrc
-h, --help, ? Show help —
-v, --version Show npkill version —

JSON Output Mode

npkill can output results as JSON for scripting and automation:

--json

Collects all results and prints them as a single JSON object when the scan is complete. 

npx npkill --json

--json-stream

Prints each result as a separate JSON object on its own line, as soon as its size and age are ready. Useful for real-time processing or large scans. 

npx npkill --json-stream | jq -r '.result.path'

Examples

Scan from home directory, sort by size

npx npkill -f -s size

Use Python profile

npx npkill -p python

Search for specific directories

npx npkill --targets "dist,.cache,.next"

Exclude certain directories

npx npkill -E "important-project,production"

Dry run (simulate)

npx npkill --dry-run

Interactive Controls

Once npkill is running, you can use these keyboard shortcuts:

Navigation

↑ / k Move up
↓ / j Move down
PgUp / u / Ctrl+u Page up
PgDown / d / Ctrl+d Page down
Home / End Go to first/last result
← / h Previous panel
→ / l Next panel (info panel)

Actions

Space / Del Delete selected directory
o Open parent directory in file explorer
/ Filter results (supports regex)
t Toggle multiselect mode
e Show errors
q / Ctrl+c Quit

Multiselect Mode

Press t to enter multiselect mode:

Space Select/deselect current item
Enter Delete all selected items
a Select/deselect all
v Select a range
t Exit multiselect without deleting