toolkit clean — Scan and Purge Dev Dependency Folders

The toolkit clean command group helps you reclaim gigabytes of disk space by locating and removing dependency folders that accumulate across your projects. It exposes two subcommands: scan to recursively discover node_modules directories and Python virtual environments (.venv, venv, env, conda) under a given path and report how much space you can recover, and purge to actually delete those folders — with a mandatory dry-run mode so you can always preview what will be removed before committing.

toolkit clean scan

Recursively search a directory for node_modules folders and Python virtual environments. For each target found, the command reports its type, size on disk, whether it is orphaned (no parent project file detected), and the total reclaimable space across all targets. Syntax

toolkit clean scan [targetPath] [options]

Arguments

Argument	Type	Required	Description
`[targetPath]`	`string`	No	Directory to scan. Defaults to the current working directory (`process.cwd()`).

Options

Option	Type	Default	Description
`-d, --depth <num>`	`number`	`5`	Maximum depth to traverse in the directory tree.
`--json`	`boolean`	`false`	Emit found targets and total reclaimable size as structured JSON.

Examples

# Scan the current directory using the default depth of 5
toolkit clean scan

# Scan a specific path, limiting traversal to 3 directory levels
toolkit clean scan ~/projects --depth 3

# Scan a web-server root and emit JSON output
toolkit clean scan /var/www --json

JSON output When you pass --json, the command writes a structured summary to stdout:

toolkit clean scan ~/projects --json

{
  "totalTargets": 2,
  "totalSizeFormatted": "1.23 GB",
  "targets": [
    {
      "type": "node_modules",
      "path": "/home/user/projects/my-app/node_modules",
      "sizeFormatted": "854 MB",
      "isOrphan": false,
      "details": { "projectName": "my-app" }
    },
    {
      "type": "python_venv",
      "path": "/home/user/projects/old-script/.venv",
      "sizeFormatted": "410 MB",
      "isOrphan": true,
      "details": { "projectName": null }
    }
  ]
}

toolkit clean purge

Delete the node_modules directories and Python virtual environments discovered under the target path. Use --dry-run to simulate the operation and see exactly how much space would be freed without touching any files. Syntax

toolkit clean purge [targetPath] [options]

Arguments

Argument	Type	Required	Description
`[targetPath]`	`string`	No	Directory to clean. Defaults to the current working directory (`process.cwd()`).

Options

Option	Type	Default	Description
`--dry-run`	`boolean`	`false`	Simulation mode: calculate and display reclaimable space without deleting any files.
`--force`	`boolean`	`false`	Skip the interactive safety confirmation prompt before purging.
`--json`	`boolean`	`false`	Emit a JSON summary of the purge results.

Examples

# Preview how much space would be freed — no files are deleted
toolkit clean purge --dry-run

# Permanently delete dependency folders in a projects directory, skipping confirmation
toolkit clean purge ~/projects --force

# Dry-run with JSON output for scripting
toolkit clean purge --dry-run --json

JSON output When you pass --json, the command writes a structured result to stdout:

toolkit clean purge --dry-run --json

{
  "dryRun": true,
  "totalTargets": 2,
  "results": [
    {
      "path": "/home/user/projects/my-app/node_modules",
      "success": true,
      "dryRun": true,
      "reclaimedBytes": 895631360,
      "reclaimedFormatted": "854 MB"
    },
    {
      "path": "/home/user/projects/old-script/.venv",
      "success": true,
      "dryRun": true,
      "reclaimedBytes": 429916160,
      "reclaimedFormatted": "410 MB"
    }
  ]
}

Always run toolkit clean purge --dry-run before the actual purge. The dry-run output shows you every path that will be deleted and the exact space that will be recovered, so there are no surprises.

Purge deletes files permanently. There is no undo. Make sure you have reinstalled or no longer need the scanned dependency folders before running without --dry-run.

​toolkit clean scan

​toolkit clean purge

toolkit clean scan

toolkit clean purge