> ## Documentation Index
> Fetch the complete documentation index at: https://toolkit.astralsolutions.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# toolkit clean — Scan and Purge Dev Dependency Folders

> toolkit clean scan and purge — find node_modules and Python venv directories, preview reclaimable disk space, and delete with dry-run safety.

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**

```bash theme={null}
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**

```bash theme={null}
# 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:

```bash theme={null}
toolkit clean scan ~/projects --json
```

```json theme={null}
{
  "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**

```bash theme={null}
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**

```bash theme={null}
# 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:

```bash theme={null}
toolkit clean purge --dry-run --json
```

```json theme={null}
{
  "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"
    }
  ]
}
```

<Tip>
  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.
</Tip>

<Warning>
  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`.
</Warning>