# Knowledge Report: @cli/popsy_cli/
## Overview
The `popsy_cli` module is a comprehensive Reddit automation CLI tool that enables automated Direct Message (DM) and comment posting using the Popsy AI API. The module provides both API-based simulation and browser-based automation capabilities.
## Module Structure
### 1. `__init__.py`
**Location**: `cli/popsy_cli/__init__.py:1-8`
- Package metadata and version information
- Author: Popsy AI
- Basic package initialization
### 2. `api.py` - Core API Client
**Location**: `cli/popsy_cli/api.py:1-609`
#### Key Components:
**Thread Data Structure** (`api.py:20-34`)
- `Thread` dataclass representing Reddit threads
- Fields: id, title, url, author, content, score, reasoning, suggested_dm, suggested_comment, subreddit_name, created_at
**PopsyAPIClient Class** (`api.py:36-255`)
- Main API client for Popsy Reddit automation
- Base URL: `https://app.popsy.ai`
- Authentication via Bearer token
- Context manager support for proper resource cleanup
**Core Methods**:
- `fetch_threads()` (`api.py:61-126`): Retrieve threads with extensive filtering options
- `mark_thread_as_seen()` (`api.py:128-142`): Mark threads as viewed
- `mark_thread_as_closed()` (`api.py:144-158`): Close processed threads
- `send_dm()` / `send_comment()` (`api.py:160-190`): Mark messages as sent
- `queue_dm()` / `unqueue_dm()` (`api.py:192-222`): Queue management for DMs
- `queue_comment()` / `unqueue_comment()` (`api.py:224-254`): Queue management for comments
**Processing Functions**:
- `process_threads_for_dm()` (`api.py:287-410`): Automated DM processing with callback support
- `process_threads_for_comment()` (`api.py:490-607`): Automated comment processing
- `parse_threads_response()` (`api.py:257-284`): Parse API responses into Thread objects
**Utility Functions**:
- `setup_logging()` (`api.py:413-444`): Configurable logging setup
- `show_configuration()` (`api.py:446-487`): Display current configuration
### 3. `dm_automation.py` - Browser Automation
**Location**: `cli/popsy_cli/dm_automation.py:1-131`
#### Key Components:
**BrowserDMSender Class** (`dm_automation.py:21-111`)
- Browser automation using Camoufox with human-like behavior
- Persistent browser context with login session storage
- macOS fingerprinting for MacBook compatibility
- Anti-detection features with randomized delays
**Core Methods**:
- `setup_browser()` (`dm_automation.py:31-54`): Initialize browser with persistent context
- `send_dm_to_user()` (`dm_automation.py:56-98`): Send DMs via browser automation
- `close()` (`dm_automation.py:100-110`): Proper browser cleanup
**Features**:
- Persistent login sessions stored in `browser_data/`
- Random delays between actions (3-5 seconds)
- Daily limit detection and handling
- Human-like cursor movement and typing
### 4. `main.py` - CLI Entry Point
**Location**: `cli/popsy_cli/main.py:1-317`
#### Key Components:
**Command Structure**:
- Main command: `popsy`
- Subcommands: `version`, `run`
- Comprehensive argument parsing with defaults and configuration file support
**Configuration Management** (`main.py:82-103`):
- Precedence: CLI args → config file → environment variables → defaults
- JSON configuration file support (`config.json`)
- Environment variable support (`POPSY_API_TOKEN`, `BASE_URL`)
**Core Parameters**:
- `--token`: API authentication
- `--mode`: DM or comment processing
- `--browser`: Enable browser automation
- `--dry-run`: Simulation mode
- `--min-relevancy`: Relevance score filtering (0-100)
- `--max-threads`: Processing limits
- Extensive filtering options for threads
**Key Functions**:
- `cmd_run()` (`main.py:48-237`): Main execution logic
- `get_version()` (`main.py:34-39`): Version retrieval
- Configuration validation and effective value resolution
## Key Features
### 1. **Dual Processing Modes**
- **DM Mode**: Send direct messages to Reddit users
- **Comment Mode**: Post comments on Reddit threads
### 2. **Automation Methods**
- **API Simulation**: Testing and dry-run capabilities
- **Browser Automation**: Real Reddit interaction via Camoufox
### 3. **Advanced Filtering**
- Relevancy score filtering
- Subreddit-specific processing
- Author deduplication
- Queue management (sent/queued status)
- Date and relevance sorting
### 4. **Logging & Monitoring**
- Comprehensive logging with configurable levels
- CSV log files for sent messages/comments
- Processing statistics and error tracking
- Daily limit detection
### 5. **Configuration Flexibility**
- Multiple configuration sources with proper precedence
- JSON configuration files
- Environment variable support
- Extensive CLI arguments
## Dependencies
- `requests`: HTTP client for API communication
- `camoufox`: Browser automation framework
- `browserforge`: Browser fingerprinting
- `dataclasses`: Type definitions
- Standard library: `argparse`, `json`, `logging`, `csv`, `time`, `random`
## Usage Patterns
```bash
# Basic DM automation with browser
popsy run --token YOUR_TOKEN --mode dm --browser
# Dry run with high relevancy filter
popsy run --token YOUR_TOKEN --dry-run --min-relevancy 90
# Comment mode with configuration file
popsy run --config my_config.json --mode comment
```
## Architecture Strengths
1. **Modular Design**: Clear separation of concerns across files
2. **Extensible**: Callback-based processing allows custom implementations
3. **Robust Error Handling**: Comprehensive exception handling and logging
4. **Configuration Management**: Flexible configuration with proper precedence
5. **Context Management**: Proper resource cleanup for browser and API clients
This CLI tool provides a complete solution for Reddit automation with both testing and production capabilities, extensive configuration options, and robust error handling.
---
# Reddit DM Automation - User Guide
## What You Need:
- MacBook with macOS 10.15 or newer
- Reddit account
- Popsy API token
- 30 minutes for setup
---
## Step 1: Install Python 3.11.9
### Check if you have Python:
```bash
python3 --version
```
### If you don't have Python 3.11.9, install it:
```bash
# Install Homebrew first (copy and paste this whole line)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
# Install Python 3.11.9
brew install python@3.11
```
---
## Step 2: Install Required Software
```bash
# Install the required libraries
pip3 install requests "camoufox[geoip]" browserforge
# Download the special browser (this takes a few minutes)
python3 -m camoufox fetch
```
---
## Step 3: Unzip and go to the folder
```bash
# Go to the folder
cd reddit-automation
```
---
## Step 4: Get Your API Token
1. **Login to Popsy Dashboard**
2. **Get your API token** from settings
3. **Set environment variable:**
```bash
export POPSY_API_TOKEN="your-token-here"
```
Or create a config file:
```bash
# Create config.json
{
"token": "your-api-token-here",
"base_url": "https://app.popsy.ai",
"min_relevancy": 10,
"max_threads": 5,
"show_new": false,
"hide_already_dmed": true,
"sort_by": "by_relevancy"
}
```
---
## Step 5: Test the Connection (NEW Unified CLI)
```bash
# Test with simulation mode (no actual DMs sent)
python3 main.py --dry-run --verbose --min-relevancy 80
# Test with detailed debugging
python3 main.py --debug --dry-run --show-new
```
---
## Step 6: Choose Your Automation Mode
### 🔹 **API Simulation Mode** (Default - Safe Testing)
```bash
# Basic simulation - see what would happen
python3 main.py --dry-run --verbose
# Live simulation with API tracking
python3 main.py --min-relevancy 80 --max-threads 3
```
### 🔹 **Live Browser Automation** (Real DM Sending)
```bash
# Live browser automation with visible browser
python3 main.py --browser --min-relevancy 80 --max-threads 3
# Headless browser automation (background)
python3 main.py --browser --headless --min-relevancy 9 --max-threads 2
```
---
## Daily Use Examples:
### **Conservative Automation** (Recommended)
```bash
# High-quality leads only, visible browser
python3 main.py --browser --min-relevancy 90 --max-threads 3 --verbose
```
### **Testing New Filters**
```bash
# Test different relevancy thresholds
python3 main.py --dry-run --min-relevancy 60 --show-new --verbose
# Test specific subreddit
python3 main.py --subreddit-id 123 --dry-run --debug
```
### **Bulk Processing** (Advanced Users)
```bash
# Background automation with higher volume
python3 main.py --browser --headless --min-relevancy 80 --max-threads 10
```
---
# How to build the package
```bash
uv build
uv run twine upload dist/*
```
Raw data
{
"_id": null,
"home_page": null,
"name": "popsy-ai",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "ai, automation, dm, lead-generation, outreach, reddit",
"author": null,
"author_email": "Popsy AI <support@popsy.ai>",
"download_url": null,
"platform": null,
"description": "# Knowledge Report: @cli/popsy_cli/\n\n## Overview\nThe `popsy_cli` module is a comprehensive Reddit automation CLI tool that enables automated Direct Message (DM) and comment posting using the Popsy AI API. The module provides both API-based simulation and browser-based automation capabilities.\n\n## Module Structure\n\n### 1. `__init__.py`\n**Location**: `cli/popsy_cli/__init__.py:1-8`\n- Package metadata and version information\n- Author: Popsy AI\n- Basic package initialization\n\n### 2. `api.py` - Core API Client\n**Location**: `cli/popsy_cli/api.py:1-609`\n\n#### Key Components:\n\n**Thread Data Structure** (`api.py:20-34`)\n- `Thread` dataclass representing Reddit threads\n- Fields: id, title, url, author, content, score, reasoning, suggested_dm, suggested_comment, subreddit_name, created_at\n\n**PopsyAPIClient Class** (`api.py:36-255`)\n- Main API client for Popsy Reddit automation\n- Base URL: `https://app.popsy.ai`\n- Authentication via Bearer token\n- Context manager support for proper resource cleanup\n\n**Core Methods**:\n- `fetch_threads()` (`api.py:61-126`): Retrieve threads with extensive filtering options\n- `mark_thread_as_seen()` (`api.py:128-142`): Mark threads as viewed\n- `mark_thread_as_closed()` (`api.py:144-158`): Close processed threads\n- `send_dm()` / `send_comment()` (`api.py:160-190`): Mark messages as sent\n- `queue_dm()` / `unqueue_dm()` (`api.py:192-222`): Queue management for DMs\n- `queue_comment()` / `unqueue_comment()` (`api.py:224-254`): Queue management for comments\n\n**Processing Functions**:\n- `process_threads_for_dm()` (`api.py:287-410`): Automated DM processing with callback support\n- `process_threads_for_comment()` (`api.py:490-607`): Automated comment processing\n- `parse_threads_response()` (`api.py:257-284`): Parse API responses into Thread objects\n\n**Utility Functions**:\n- `setup_logging()` (`api.py:413-444`): Configurable logging setup\n- `show_configuration()` (`api.py:446-487`): Display current configuration\n\n### 3. `dm_automation.py` - Browser Automation\n**Location**: `cli/popsy_cli/dm_automation.py:1-131`\n\n#### Key Components:\n\n**BrowserDMSender Class** (`dm_automation.py:21-111`)\n- Browser automation using Camoufox with human-like behavior\n- Persistent browser context with login session storage\n- macOS fingerprinting for MacBook compatibility\n- Anti-detection features with randomized delays\n\n**Core Methods**:\n- `setup_browser()` (`dm_automation.py:31-54`): Initialize browser with persistent context\n- `send_dm_to_user()` (`dm_automation.py:56-98`): Send DMs via browser automation\n- `close()` (`dm_automation.py:100-110`): Proper browser cleanup\n\n**Features**:\n- Persistent login sessions stored in `browser_data/`\n- Random delays between actions (3-5 seconds)\n- Daily limit detection and handling\n- Human-like cursor movement and typing\n\n### 4. `main.py` - CLI Entry Point\n**Location**: `cli/popsy_cli/main.py:1-317`\n\n#### Key Components:\n\n**Command Structure**:\n- Main command: `popsy`\n- Subcommands: `version`, `run`\n- Comprehensive argument parsing with defaults and configuration file support\n\n**Configuration Management** (`main.py:82-103`):\n- Precedence: CLI args \u2192 config file \u2192 environment variables \u2192 defaults\n- JSON configuration file support (`config.json`)\n- Environment variable support (`POPSY_API_TOKEN`, `BASE_URL`)\n\n**Core Parameters**:\n- `--token`: API authentication\n- `--mode`: DM or comment processing\n- `--browser`: Enable browser automation\n- `--dry-run`: Simulation mode\n- `--min-relevancy`: Relevance score filtering (0-100)\n- `--max-threads`: Processing limits\n- Extensive filtering options for threads\n\n**Key Functions**:\n- `cmd_run()` (`main.py:48-237`): Main execution logic\n- `get_version()` (`main.py:34-39`): Version retrieval\n- Configuration validation and effective value resolution\n\n## Key Features\n\n### 1. **Dual Processing Modes**\n- **DM Mode**: Send direct messages to Reddit users\n- **Comment Mode**: Post comments on Reddit threads\n\n### 2. **Automation Methods**\n- **API Simulation**: Testing and dry-run capabilities\n- **Browser Automation**: Real Reddit interaction via Camoufox\n\n### 3. **Advanced Filtering**\n- Relevancy score filtering\n- Subreddit-specific processing\n- Author deduplication\n- Queue management (sent/queued status)\n- Date and relevance sorting\n\n### 4. **Logging & Monitoring**\n- Comprehensive logging with configurable levels\n- CSV log files for sent messages/comments\n- Processing statistics and error tracking\n- Daily limit detection\n\n### 5. **Configuration Flexibility**\n- Multiple configuration sources with proper precedence\n- JSON configuration files\n- Environment variable support\n- Extensive CLI arguments\n\n## Dependencies\n- `requests`: HTTP client for API communication\n- `camoufox`: Browser automation framework\n- `browserforge`: Browser fingerprinting\n- `dataclasses`: Type definitions\n- Standard library: `argparse`, `json`, `logging`, `csv`, `time`, `random`\n\n## Usage Patterns\n```bash\n# Basic DM automation with browser\npopsy run --token YOUR_TOKEN --mode dm --browser\n\n# Dry run with high relevancy filter\npopsy run --token YOUR_TOKEN --dry-run --min-relevancy 90\n\n# Comment mode with configuration file\npopsy run --config my_config.json --mode comment\n```\n\n## Architecture Strengths\n1. **Modular Design**: Clear separation of concerns across files\n2. **Extensible**: Callback-based processing allows custom implementations\n3. **Robust Error Handling**: Comprehensive exception handling and logging\n4. **Configuration Management**: Flexible configuration with proper precedence\n5. **Context Management**: Proper resource cleanup for browser and API clients\n\nThis CLI tool provides a complete solution for Reddit automation with both testing and production capabilities, extensive configuration options, and robust error handling.\n\n---\n\n# Reddit DM Automation - User Guide\n\n## What You Need:\n- MacBook with macOS 10.15 or newer\n- Reddit account\n- Popsy API token\n- 30 minutes for setup\n\n---\n\n## Step 1: Install Python 3.11.9\n\n### Check if you have Python:\n```bash\npython3 --version\n```\n\n### If you don't have Python 3.11.9, install it:\n```bash\n# Install Homebrew first (copy and paste this whole line)\n/bin/bash -c \"$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)\"\n\n# Install Python 3.11.9\nbrew install python@3.11\n```\n\n---\n\n## Step 2: Install Required Software\n\n```bash\n# Install the required libraries\npip3 install requests \"camoufox[geoip]\" browserforge\n\n# Download the special browser (this takes a few minutes)\npython3 -m camoufox fetch\n```\n\n---\n\n## Step 3: Unzip and go to the folder\n\n```bash\n# Go to the folder\ncd reddit-automation\n```\n\n---\n\n## Step 4: Get Your API Token\n\n1. **Login to Popsy Dashboard**\n2. **Get your API token** from settings\n3. **Set environment variable:**\n```bash\nexport POPSY_API_TOKEN=\"your-token-here\"\n```\n\nOr create a config file:\n```bash\n# Create config.json\n{\n \"token\": \"your-api-token-here\",\n \"base_url\": \"https://app.popsy.ai\",\n \"min_relevancy\": 10,\n \"max_threads\": 5,\n \"show_new\": false,\n \"hide_already_dmed\": true,\n \"sort_by\": \"by_relevancy\"\n}\n```\n\n---\n\n## Step 5: Test the Connection (NEW Unified CLI)\n\n```bash\n# Test with simulation mode (no actual DMs sent)\npython3 main.py --dry-run --verbose --min-relevancy 80\n\n# Test with detailed debugging\npython3 main.py --debug --dry-run --show-new\n```\n\n---\n\n## Step 6: Choose Your Automation Mode\n\n### \ud83d\udd39 **API Simulation Mode** (Default - Safe Testing)\n```bash\n# Basic simulation - see what would happen\npython3 main.py --dry-run --verbose\n\n# Live simulation with API tracking\npython3 main.py --min-relevancy 80 --max-threads 3\n```\n\n### \ud83d\udd39 **Live Browser Automation** (Real DM Sending)\n```bash\n# Live browser automation with visible browser\npython3 main.py --browser --min-relevancy 80 --max-threads 3\n\n# Headless browser automation (background)\npython3 main.py --browser --headless --min-relevancy 9 --max-threads 2\n```\n\n---\n\n## Daily Use Examples:\n\n### **Conservative Automation** (Recommended)\n```bash\n# High-quality leads only, visible browser\npython3 main.py --browser --min-relevancy 90 --max-threads 3 --verbose\n```\n\n### **Testing New Filters**\n```bash\n# Test different relevancy thresholds\npython3 main.py --dry-run --min-relevancy 60 --show-new --verbose\n\n# Test specific subreddit\npython3 main.py --subreddit-id 123 --dry-run --debug\n```\n\n### **Bulk Processing** (Advanced Users)\n```bash\n# Background automation with higher volume\npython3 main.py --browser --headless --min-relevancy 80 --max-threads 10\n```\n\n---\n\n# How to build the package\n\n```bash\nuv build\nuv run twine upload dist/*\n```\n",
"bugtrack_url": null,
"license": "Copyright 2025 Popsy Labs, Inc.",
"summary": "Reddit DM automation CLI using Popsy AI for lead generation and outreach",
"version": "0.0.8",
"project_urls": {
"Homepage": "https://popsy.ai"
},
"split_keywords": [
"ai",
" automation",
" dm",
" lead-generation",
" outreach",
" reddit"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "8cae13c7f680b62a25cc93763087ab91b71978dd1913b2967b9e20ab830a7a9d",
"md5": "02ef9494c321a3a0c2fa2794bc8d285d",
"sha256": "01b04df83bb73d66db582e7c10f86a0703eb016c782d36a9bbcde82a25b1889b"
},
"downloads": -1,
"filename": "popsy_ai-0.0.8-py3-none-any.whl",
"has_sig": false,
"md5_digest": "02ef9494c321a3a0c2fa2794bc8d285d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 17505,
"upload_time": "2025-07-30T13:40:59",
"upload_time_iso_8601": "2025-07-30T13:40:59.586906Z",
"url": "https://files.pythonhosted.org/packages/8c/ae/13c7f680b62a25cc93763087ab91b71978dd1913b2967b9e20ab830a7a9d/popsy_ai-0.0.8-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-30 13:40:59",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "popsy-ai"
}
JSON