appclean

v2.0.3

Published

10 days ago

A powerful CLI tool to intelligently find and safely uninstall applications from your system with all their artifacts

Downloads

486

0High
0Medium
0Low

appclean

uninstaller app-management cli cross-platform npm brew package-manager cleanup

AppClean 🧹

Intelligently find and safely uninstall applications with all their artifacts

A powerful, cross-platform tool for developers, system administrators, and everyone

What is AppClean?

AppClean is an intelligent application uninstaller that completely removes apps from your system along with all their hidden files, configurations, caches, and leftover data. It supports apps installed via npm, Homebrew, apt, yum, and custom installers across macOS, Linux, and Windows.

Why AppClean?

🎯 Complete Removal - Finds and removes all app-related files, not just the executable
🛡️ Safe & Smart - Preview what will be deleted before confirming
💾 Backup Option - Create backups before removal for peace of mind
🎨 Beautiful Interface - Modern GUI makes app management easy for everyone
⚡ Fast & Efficient - ~50KB bundle, <100ms API responses
🔌 Programmable - Full REST API for automation and integration

✨ What's New in v2.0.0

🎉 Complete GUI Overhaul - A brand new modern single-page application (SPA) interface for intelligent app management!

New Features

🎨 Beautiful SPA Interface - Clean, minimal design with dark mode support
📊 Dashboard - System statistics, disk usage gauge, recent activity log
🔍 Smart App Search - Fuzzy search, filter by installation method, sort by name/size/date
📂 Detailed Analysis - Visual artifacts list, size breakdown pie chart, category breakdown
👁️ Preview Mode - See exactly what will be deleted before confirming
🛡️ Safe Removal - Dual confirmation dialogs, optional backup creation
🌙 Dark Mode - Beautiful theme with persistent preference
🔌 REST API - Full API endpoints for integration
⚡ High Performance - ~50KB gzipped, <100ms API response time

Quick Start

1. Install AppClean

npm install -g [email protected]

2. Launch the GUI (Recommended)

appclean gui

Then open http://localhost:3000 in your browser.

3. Or Use the CLI

# List all apps
appclean list

# Search for an app
appclean search <app-name>

# Analyze app and artifacts
appclean analyze <app-name>

# Remove app (with confirmation)
appclean remove <app-name>

Features

🎨 Modern GUI Interface

Dashboard View

📊 Total apps, total space used, session metrics
💾 Real-time disk usage gauge with health indicators
📜 Recent activity log showing removed apps
🚀 Quick action buttons

App Discovery (#/apps)

🔍 Real-time search with fuzzy matching
🏷️ Filter by installation method (npm, Homebrew, apt, yum, custom)
📊 Sort by name, size, or date installed
📦 Visual app cards with version and size
📄 Infinite scroll pagination

App Analysis (#/apps/:appName)

📂 Complete artifact listing with file paths
📈 Visual pie chart showing size breakdown
📋 Category breakdown (binaries, configs, caches, data, logs)
👁️ Preview mode showing what will be deleted
🗑️ Safe removal with dual confirmation
💾 Optional backup creation before removal

Settings

🔄 Version checking and update notifications
🚀 One-click upgrade to latest version
🎨 Theme toggle (light/dark mode)
ℹ️ About section with documentation
⚠️ Danger zone for uninstalling AppClean

💻 Powerful CLI

Find Apps

Detect apps from npm, yarn, pnpm, Homebrew, apt, yum, dnf
Search by name with instant results
Show app version and installation method

Analyze

Find all related files (binaries, configs, caches, logs)
See how much space each app uses
Preview what will be deleted before removing

Remove Safely

Dry-run mode to preview first
Backup option before deletion
Confirmation prompts to prevent accidents
Error reporting for failed deletions

Manage

Check for updates: appclean check-update
Upgrade automatically: appclean upgrade
Uninstall AppClean: appclean uninstall

GUI vs CLI

| Feature | GUI | CLI | |---------|-----|-----| | User-Friendly | ✅ Great for everyone | ✅ Great for power users | | Visuals | ✅ Charts, cards, animations | ❌ Text-based | | Speed | ✅ Fast with API | ✅ Very fast | | Automation | ❌ Interactive | ✅ Scriptable | | Remote Access | ✅ Via network | ❌ Local only | | Learning Curve | ✅ Minimal | ⚠️ Moderate |

Recommendation: Use the GUI for discovery and management, CLI for scripting and automation.

Common Tasks

Using the GUI

# Start the GUI
appclean gui

# Open http://localhost:3000
# Then:
# 1. Click "Apps" to browse installed applications
# 2. Search for an app by name
# 3. Click app card to see details
# 4. Click "Preview Removal" to see what will be deleted
# 5. Click "Remove App" to uninstall (with confirmation)

Using the CLI

# Find and remove an app
appclean search firefox
appclean analyze firefox
appclean remove firefox --dry-run  # Preview first
appclean remove firefox             # Actually remove

# Remove multiple apps
appclean list
appclean remove <app1>
appclean remove <app2>

# Backup before removing
appclean remove <app-name> --backup

# Use without confirmation
appclean remove <app-name> --force

All Commands

GUI Server

appclean gui                 # Start GUI on port 3000
appclean gui --port 8080    # Use custom port

Search & List

appclean search <query>     # Find apps by name
appclean list               # Show all installed apps
appclean analyze <app>      # View app details and files

Remove Apps

appclean remove <app>                # Remove app (with confirmation)
appclean remove <app> --dry-run      # Preview only
appclean remove <app> --backup       # Create backup first
appclean remove <app> --force        # Skip confirmation

Update AppClean

appclean upgrade            # Update to latest version
appclean check-update       # Check for updates
appclean --version          # Show current version

Uninstall

appclean uninstall          # Remove AppClean (with confirmation)
appclean uninstall --force  # Remove without confirmation

API Documentation

The GUI server provides a REST API for integration with other tools.

Base URL

http://localhost:3000

Endpoints

Get Dashboard Statistics

curl http://localhost:3000/api/dashboard/stats

Response:

{
  "success": true,
  "data": {
    "totalApps": 99,
    "totalSpaceUsed": 4236604496,
    "sessionAppsRemoved": 0,
    "sessionSpaceFreed": 0,
    "diskUsagePercent": 12,
    "recentlyRemoved": []
  }
}

List Applications

curl 'http://localhost:3000/api/apps/list?limit=20&offset=0'

Response:

{
  "success": true,
  "data": {
    "apps": [...],
    "total": 99,
    "page": 1,
    "pageSize": 20
  }
}

Search Applications

curl 'http://localhost:3000/api/apps/search?q=node&method=npm&sort=name'

Analyze Application

curl 'http://localhost:3000/api/apps/node/analysis'

Response:

{
  "success": true,
  "data": {
    "app": {...},
    "artifacts": [...],
    "totalSize": 52428800,
    "breakdown": {
      "binaries": 5000000,
      "configs": 2000000,
      "caches": 45000000,
      "data": 100000,
      "logs": 328800
    }
  }
}

Remove Application

curl -X POST 'http://localhost:3000/api/apps/node/remove' \
  -H 'Content-Type: application/json' \
  -d '{"dryRun": false, "createBackup": true}'

Check Version

curl 'http://localhost:3000/api/version'

Upgrade AppClean

curl -X POST 'http://localhost:3000/api/upgrade'

Uninstall AppClean

curl -X POST 'http://localhost:3000/api/uninstall'

Examples

Remove Node.js package globally

# Using GUI: Click on app → Preview → Remove
# Using CLI:
appclean remove express

Remove Homebrew app

# Using GUI: Search "spotify" → Click → Remove
# Using CLI:
appclean remove spotify

Remove system package

# Using GUI: Search "vim" → Filter by apt → Click → Remove
# Using CLI:
sudo appclean remove vim

Preview before removing

# Using GUI: Click "Preview Removal" button
# Using CLI:
appclean remove chrome --dry-run
# Review output, then:
appclean remove chrome

Create backup before removing

# Using GUI: Automatic backup option is shown
# Using CLI:
appclean remove myapp --backup

Use custom GUI port

appclean gui --port 8080
# Open http://localhost:8080

What Gets Removed?

AppClean intelligently finds and removes:

✓ Application binaries and executables
✓ Configuration files (.config, .local, etc)
✓ Cache directories and files
✓ Log files and directories
✓ Data files and user data
✓ Launch agents/daemons (macOS)
✓ Systemd services (Linux)
✓ Man pages and documentation
✓ Package manager metadata

Platform Support

| Feature | macOS | Linux | Windows | |---------|-------|-------|---------| | npm/yarn/pnpm | ✓ | ✓ | ✓ | | Homebrew | ✓ | ✓ | - | | apt/yum/dnf | - | ✓ | - | | GUI | ✓ | ✓ | ✓ | | CLI | ✓ | ✓ | ✓ | | Custom apps | ✓ | ✓ | ✓ |

Architecture

Technology Stack

GUI (Client)

ES2020 JavaScript modules
Hash-based SPA routing
Event-driven state management
CSS with design tokens and animations
Responsive layout (Flexbox, Grid)

Server

Native Node.js HTTP module (no Express)
TypeScript with strict mode
RESTful API design
CORS enabled

Core

Intelligent app detection
Multi-package-manager support
Artifact discovery and categorization
Safe removal with validation

Directory Structure

src/
├── ui/
│   ├── client/              # SPA application
│   │   ├── pages/           # Dashboard, Apps, Settings
│   │   ├── state/           # Reactive stores
│   │   ├── styles/          # CSS design system
│   │   ├── utils/           # Router, formatting
│   │   └── app.ts           # SPA entry point
│   ├── server/              # API backend
│   │   ├── routes/          # API endpoints
│   │   ├── services/        # Business logic
│   │   └── middleware/      # Request handling
│   └── guiServer.ts         # HTTP server
├── core/                    # App detection & removal
├── managers/                # Package manager integrations
└── utils/                   # Utilities

Performance

Bundle Size: ~50KB gzipped (no frameworks)
API Response: <100ms per request
Page Load: <2 seconds
Startup Time: <1 second
Memory Usage: Minimal footprint

Tips & Best Practices

💡 Always preview first

# GUI: Click "Preview Removal"
# CLI: Use --dry-run flag
appclean remove myapp --dry-run

💡 Create backups for important apps

# GUI: Backup option is shown before removal
# CLI: Use --backup flag
appclean remove myapp --backup

💡 Use the GUI for visual browsing

appclean gui
# Open http://localhost:3000
# Visual cards and charts make it easy

💡 Use CLI for scripting and automation

# In shell scripts or CI/CD pipelines
appclean remove myapp --force

💡 Check updates regularly

appclean check-update
# Or use GUI: Settings → Check for Updates

Permissions

macOS/Linux: May need sudo for system packages
```
sudo appclean remove system-package
```
Windows: May need to run as Administrator

Troubleshooting

"Permission denied" error

# Try with sudo
sudo appclean remove <app>

App not found

# Search for partial name
appclean search <partial-name>
# Or use GUI search with fuzzy matching

GUI won't start

# Check if port 3000 is in use
# Use custom port:
appclean gui --port 8080

Want to preview without removing

# Using GUI: Click "Preview Removal"
# Using CLI: Use --dry-run flag
appclean remove <app> --dry-run

Want to restore from backup

# Backups are saved in ~/.appclean-backups/
ls ~/.appclean-backups/
# Manually restore from tar.gz if needed

Safety Guarantees

✅ All actions require confirmation (unless --force is used) ✅ Preview mode available - see what will be deleted first ✅ Backup option available - protect important data ✅ No data loss - only removes application files ✅ Easy to reinstall - use npm/brew/apt to reinstall apps ✅ Dry-run mode - test before actual removal

Getting Help

# Show all commands
appclean --help

# Get help for specific command
appclean remove --help

# Check your version
appclean --version

# Check if update available
appclean check-update

License

MIT License - Free to use and modify. See LICENSE file for details.

Support & Community

📝 Report Issues: https://github.com/praveenkay/AppClean/issues 💬 Discussions: https://github.com/praveenkay/AppClean/discussions 🌟 Star if you find it useful! 📖 Documentation: https://github.com/praveenkay/AppClean#readme

Changelog

v2.0.0 (Current)

🎉 Complete GUI overhaul with modern SPA interface
📊 Dashboard with statistics and activity log
🔍 Advanced search with filtering and sorting
📂 Detailed artifact analysis with charts
🛡️ Safe removal with preview and backup
🌙 Dark mode support
🔌 REST API endpoints
📱 Responsive design (mobile, tablet, desktop)

v1.9.0

Version management and upgrade system
Basic web interface
Enhanced CLI functionality

Made with ❤️ by Praveen Kothapally

AppClean - Making app removal intelligent, safe, and beautiful. ✨

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

AppClean 🧹

What is AppClean?

Why AppClean?

✨ What's New in v2.0.0

New Features

Quick Start

1. Install AppClean

2. Launch the GUI (Recommended)

3. Or Use the CLI

Features

🎨 Modern GUI Interface

💻 Powerful CLI

GUI vs CLI

Common Tasks

Using the GUI

Using the CLI

All Commands

GUI Server

Search & List

Remove Apps

Update AppClean

Uninstall

API Documentation

Base URL

Endpoints

Examples

Remove Node.js package globally

Remove Homebrew app

Remove system package

Preview before removing

Create backup before removing

Use custom GUI port

What Gets Removed?

Platform Support

Architecture

Technology Stack

Directory Structure

Performance

Tips & Best Practices

Permissions

Troubleshooting

Safety Guarantees

Getting Help

License

Support & Community

Changelog

v2.0.0 (Current)

v1.9.0