🔥 Xpost Pulverizer

Xpost Pulverizer is a powerful Python tool for bulk-deleting your old X (Twitter) tweets. It works by parsing your easily requested X Data Archive and filtering tweets down locally before sending deletion requests via the Twitter v2 API.

It features two interfaces: a CLI Hacker Dashboard and a Textual Terminal UI (TUI).

✨ Features

• Double Interface: Choose between a high-speed CLI dashboard or a visual TUI control panel.
• Dry Run by Default: Test your filters safely. It will literally NEVER delete anything unless you explicitly arm the live mode.
• Complex Filtering:
  • 📅 Date Ranges: Delete tweets sent before, after, or between specific dates.
  • 💬 Keywords: Wipe tweets containing specific cringe words or starting with prefixes (e.g., RT @).
  • 📉 Engagement: Clean out tweets that flopped (e.g., less than 5 likes / 2 retweets).
• Rate Limit Armor: Automatically detects Twitter's strict API rate limits, initiates a 15-minute wait, and securely resumes the queue without crashing.
• Asynchronous & Thread-Safe: The TUI runs API tasks in the background, keeping the interface snappy and responsive.

---

🚀 Setup

1. Installation

Option 1: NPM (Easiest) You can install the tool globally via NPM. This will install all Python dependencies and make the tool available as a terminal command:

npm install -g xpost-pulverizer

Option 2: Docker If you have Docker and Docker Compose installed:

git clone https://github.com/radikonreturn/Xpost_Pulverizer.git
cd Xpost_Pulverizer
touch pulverizer_log.txt  # Initialize the log file for Docker mounting
docker-compose build

Option 3: Manual Installation (Git Clone) Ensure you have Python 3.10+ installed.

git clone https://github.com/radikonreturn/Xpost_Pulverizer.git
cd Xpost_Pulverizer

# Install dependencies
pip install -r requirements.txt

2. Getting Your Data Archive

1. Open X (Twitter) on the web.
2. Go to Settings and privacy > Your account > Download an archive of your data.
3. Once downloaded and extracted, find the file data/tweets.js.
4. Copy tweets.js into this tool's data/ folder (create the folder if it doesn't exist):

   Xpost_Pulverizer/
   └── data/
       └── tweets.js
   

3. Getting API Keys

You need a Free Twitter Developer Account.

1. Go to the Twitter Developer Portal.
2. Create a Project and an App.
3. Under User Authentication Settings, enable OAuth 1.0a and set App Permissions to Read and Write.
4. Generate your keys: API Key, API Key Secret, Access Token, and Access Token Secret.

---

🖥️ Usage: The Terminal UI (Recommended)

The interactive TUI gives you a visual dashboard to configure filters, preview tweets, and monitor live deletions.

# If installed via NPM:
xpost-pulverizer-tui

# If installed manually:
python xpost_pulverizer_tui.py

# If using Docker:
docker-compose run --rm xpost-pulverizer

• Sidebar: Enter your API Keys and dial in your filters.
• Preview Table: Hit Load Archive to parse your data locally. The table will populate with the tweets matching your filters.
• Dry Run: Press 🟢 DRY RUN to simulate the deletion queue in the Event Log.
• Live Delete: Toggle the Dry Run switch off and hit 🔴 DELETE to start nuking your posts permanently. Press q at any point to safely emergency-stop the worker thread.

---

⌨️ Usage: The Hacker CLI

If you prefer scripting or running commands directly, use the CLI. It features a beautiful colorama box-drawing UI.

# View all available flags (Manually)
python xpost_pulverizer.py --help

# Or if installed via NPM
xpost-pulverizer --help

Environment Variables

For the CLI, it's recommended to store your API keys in your environment variables:

export XPOST_API_KEY="your_api_key_here"
export XPOST_API_SECRET="your_api_secret_here"
export XPOST_ACCESS_TOKEN="your_access_token_here"
export XPOST_ACCESS_TOKEN_SECRET="your_access_token_secret_here"
``` *(In Windows PowerShell, use `$env:XPOST_API_KEY="...`)*

### CLI Examples

**Safe Dry Run (List all tweets)**
```bash
xpost-pulverizer -a data/tweets.js

Delete Old Retweets

xpost-pulverizer -a data/tweets.js -e 2022-12-31 --starts-with "RT @" --delete

Delete Low-Engagement Cringe

xpost-pulverizer -a data/tweets.js --contains cringe ratio --max-likes 2 --delete

(Note: If installed manually without NPM, replace xpost-pulverizer with python xpost_pulverizer.py or use Docker).

---

⚠️ Warning

• Permanent Action: Tweets deleted through the API cannot be recovered. Always verify your filters using a Dry Run first.
• Rate Limits: The free Twitter v2 API restricts you to 50 deletes per 24 hours (or 1,500 per month depending on tier changes). If you hit the ceiling, the script will gracefully pause and wait, but it may take days to clear hundreds of thousands of tweets.

📝 Logs

Every action (DRY, DELETE, API ERROR) is logged to pulverizer_log.txt. The log file automatically rotates with date-stamps when it exceeds 1MB.