# ReclaimSpace CLI

npm version license npm downloads documentation site npm package github stars

**A CLI tool to reclaim disk space by finding and removing regeneratable development folders.** It behaves like `npx npkill`, but goes further by detecting multiple categories of heavy folders/files, providing a navigable grouped CLI, and focusing on modern tech stacks like Shopify and React Router—all without a single runtime dependency. ## Usage Here are some common ways to use `reclaimspace`: **To interactively select and delete items (default):** This is the default behavior. It lists all the folders, and you can select which ones to delete. ```bash npx reclaimspace ``` **To directly delete everything (auto-delete):** This will find all reclaimable items and delete them automatically without confirmation. ```bash npx reclaimspace --yes ``` **To see what would be deleted (dry run):** This will list all the items that can be deleted but won't actually delete anything. ```bash npx reclaimspace --dry ``` **To run in a specific folder:** You can specify one or more directories to scan. ```bash npx reclaimspace ``` **To display the version number:** ```bash npx reclaimspace --version # or npx reclaimspace -v ``` **To display the help message:** ```bash npx reclaimspace --help ``` **To combine flags and folders:** You can combine any of the flags with a specific folder. For example, to auto-delete all items in the `my-project` directory: ```bash npx reclaimspace --yes my-project ``` **To enable build analysis:** This will enable build analysis logs. ```bash npx reclaimspace --build-analysis ``` **To ignore certain folders:** You can temporarily exclude folders from the scan by providing a comma-separated list of patterns. ```bash npx reclaimspace --ignore "node_modules,dist" ``` **To ignore certain folders permanently (global):** You can permanently exclude folders from the scan by providing a comma-separated list of patterns. This will update the global `.reclaimspacerc` file (in `%APPDATA%\reclaimspace\` on Windows, `~/Library/Application Support/reclaimspace/` on macOS, or `~/.config/reclaimspace/` on Linux) using the `--save` or `-s` flag. ```bash npx reclaimspace --ignore "node_modules,dist" --save ``` **To include only specific folders:** You can specify a comma-separated list of patterns to include in the scan. When this flag is used, only folders matching these patterns will be considered, overriding the default detected items. ```bash npx reclaimspace --include "my-custom-build,temp-files" ``` **To deep clean package manager caches:** This will clear caches for npm, pnpm, yarn, pip, and other detected package managers. When the cache size doesn't change after cleaning, a descriptive reason is shown explaining why (e.g., pnpm's `store prune` only removes unreferenced packages). ```bash npx reclaimspace --deep-clean # or use the short flag npx reclaimspace -dc ``` You can also combine it with a scan: ```bash npx reclaimspace --yes --deep-clean npx reclaimspace --yes -dc ``` ## Configuration You can create a `.reclaimspacerc` file in the root of your project to specify folders and patterns to ignore. This is useful for excluding project-specific build folders or other directories that you don't want to be scanned. ### Global Ignore Patterns You can also save ignore patterns globally via the `--save` flag. Global patterns are stored in a `.reclaimspacerc` file inside your platform's config directory: - **Windows:** `%APPDATA%\reclaimspace\.reclaimspacerc` - **macOS:** `~/Library/Application Support/reclaimspace/.reclaimspacerc` - **Linux:** `~/.config/reclaimspace/.reclaimspacerc` ### Default Ignore Patterns The tool automatically excludes common system and editor directories: `Program Files`, `Applications`, `System`, `Library`, `.vscode`, `.cursor`, `.idea`, `.pnpm-store`, `.vitest-attachments`, `src`, `lib`, `components`, `assets`, and more. ### Example `.reclaimspacerc` file: ``` # Ignore all node_modules folders node_modules # Ignore a specific build folder my-project/dist ``` ## Features - **Interactive Deletion:** Navigate through a list of found items using arrow keys, space to select, and Enter to proceed. - **Zero Runtime Dependencies:** Built from the ground up with native Node.js APIs for maximum speed and security. No `node_modules` at runtime! - **Categorized & Grouped:** Results are grouped by type (Node Modules, Build Folders, etc.) for clarity. - **Size Information:** See the size of each item and the total reclaimable space. - **Concurrent Scanning:** ReclaimSpace uses a concurrent scanner to quickly find and process files. - **Build Artifact Detection:** It intelligently detects build folders by looking for common build artifacts, including Rust `target` directories. - **Auto-Delete Mode:** Use the `--yes` flag to delete all found items without confirmation. - **Dry Run Mode:** Use the `--dry` flag to see what would be deleted without actually deleting anything. - **Ignore Patterns:** Exclude specific folders or patterns using a `.reclaimspacerc` file or the `--ignore` flag. - **Interactive UI:** Supports 'a' to select all and 'i' to invert selection. - **Keyboard Protection:** Terminal input is suppressed during deletion, preventing accidental keystrokes (like Enter) from corrupting the output. - **Build Analysis:** Use the `--build-analysis` flag to see inferred project types, including Rust, and common build patterns. - **Include Patterns:** Use the `--include` flag to scan only folders matching specific patterns. - **Global Config:** Ignore patterns can be saved globally via `--save`, applying across all projects. - **Deep Clean Mode:** Use the `--deep-clean` (`-dc`) flag to clear package manager caches (npm, pnpm, yarn, pip) for even more reclaimed space. Shows descriptive reasons when cache size is unchanged. - **Cool Logo:** Displays a cool logo when you run the tool. ## Detected Items `reclaimspace` detects the following categories: 1. **Node Modules** - `node_modules` 2. **Build/Cache Folders** - `.next`, `dist`, `build`, `storybook-static`, `.nuxt`, `.output`, `.svelte-kit`, `.angular`, `out`, `.expo`, `.turbo`, `.cache`, `.shopify`, `.react-router`, `.tanstack`, `.vite-ssg-temp` - `.rollup.cache`, `.parcel-cache`, `.vite`, `.astro`, `.solid`, `.remix`, `.docusaurus`, `.eleventy-cache`, `.gatsby-cache`, `public/build`, `target` - `.eslintcache`, `.stylelintcache`, `.prettiercache`, `.tsbuildinfo`, `.swc`, `.nx`, `.wwebjs_cache`, `.wwebjs_auth` 3. **Testing/Reporting Folders** - `coverage`, `.nyc_output`, `.pytest_cache`, `.tox`, `htmlcov` 4. **Miscellaneous Dev Junk** - `.venv`, `venv`, `env` (Python Virtual Environments) - `__pycache__`, `.mypy_cache`, `.ruff_cache` (Python caches) - `vendor` (Go/PHP dependencies) - `.vagrant`, `.terraform` (Infrastructure tools) ## Changelog See the [CHANGELOG.md](./CHANGELOG.md) for a full history of changes and contributor credits. ## Contributing Contributions are welcome! Please read our [contributing guidelines](./CONTRIBUTING.md) to get started. ## License This project is licensed under the ISC License. See the [LICENSE](./LICENSE) file for details.