SEO Automation Tool

A comprehensive WordPress SEO automation suite that leverages AI to analyze, categorize, and optimize content across multiple sites.

🚀 Overview

This tool helps you manage SEO for multiple WordPress sites by:

• Exporting all posts with complete metadata
• Using AI to analyze content and provide actionable recommendations
• Suggesting optimal site placement and categorization
• Providing SEO quality analysis for titles and meta descriptions
• Supporting manual approval of all recommendations

📋 Features

• Multi-site support: Works with multiple WordPress installations
• AI-powered analysis: Uses Claude AI for content recommendations
• Category management: Suggests optimal categories and site placement
• SEO quality checks: Analyzes title and meta description quality
• Manual approval: All recommendations require human approval
• Configurable: Uses both .env and YAML configuration files
• Modular design: Each workflow is independent and chainable

🛠️ Prerequisites

1. Python 3.8+
2. WordPress sites with REST API access
3. App passwords for WordPress authentication
4. OpenRouter API key for AI analysis

📦 Installation

1. Clone the repository:

   git clone <repository-url>
   cd seo
   

2. Create a virtual environment:

   python3 -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   

3. Install dependencies:

   pip install -r requirements.txt
   

4. Configure your environment:

   cp .env.example .env
   # Edit .env with your credentials
   

5. Update the configuration in config.yaml if needed

🚀 Quick Start

Option 1: Full Pipeline (Recommended)

./seo full_pipeline

Option 2: Step-by-Step

# Export all posts
./seo export

# Analyze with AI
./seo analyze

# Check SEO quality
./seo seo_check

Option 3: Chain Commands

./seo export && \
./seo analyze && \
./seo seo_check

📁 Workflows

1. Export Posts

./seo export

Exports all posts from configured WordPress sites with complete metadata.

• Output: output/all_posts_YYYY-MM-DD.csv

2. AI Analysis

./seo analyze [csv_file]

Uses AI to analyze posts and provide recommendations for site placement, categorization, and content consolidation.

• Input: CSV file (optional, uses latest export if not provided)
• Output: output/posts_with_ai_recommendations_*.csv

3. SEO Quality Check

./seo seo_check

Analyzes title and meta description quality with SEO scoring.

• Output: output/seo_analysis_*.csv and output/seo_analysis_*.html

4. Category Management

./seo categories

Manages categories across all sites with AI-powered recommendations.

• Output: output/category_assignments_*.csv, output/proposed_categories_*.csv

5. Approve Recommendations

./seo approve [file1.csv] [file2.csv] ...

Interactive approval system for all recommendations.

• Input: CSV files with recommendations (optional, auto-detects if not provided)
• Output: output/approved_recommendations_*.csv, output/rejected_recommendations_*.csv

6. Recategorize Posts

./seo recategorize [csv_file]

Recategorize posts with AI suggestions.

• Input: CSV file (optional, uses latest export if not provided)
• Output: output/posts_with_recategorization_*.csv

7. Full Pipeline

./seo full_pipeline

Runs the complete workflow: export → analyze → seo_check

8. Analytics Import

./seo analytics ga4_export.csv gsc_export.csv

Imports Google Analytics and Search Console data.

• Input: GA4 and GSC CSV exports
• Output: output/posts_with_analytics.csv

9. Content Gaps

./seo gaps

Analyzes content gaps and suggests new content opportunities.

• Output: output/content_gaps.csv

10. Keyword Opportunities

./seo opportunities

Analyzes keyword opportunities for SEO optimization.

• Output: output/keyword_opportunities.csv

11. Report Generation

./seo report

Generates comprehensive SEO optimization reports.

• Output: output/seo_optimization_report.md

12. Status Check

./seo status

Shows status of output files.

🖥️ CLI Usage

The SEO automation tool provides a simple, intuitive CLI inspired by Ruby on Rails:

./seo help                    # Show available commands
./seo export                  # Export all posts from WordPress sites
./seo analyze                 # Analyze posts with AI for recommendations
./seo recategorize            # Recategorize posts with AI
./seo seo_check               # Check SEO quality of titles/descriptions
./seo categories              # Manage categories across sites
./seo approve                 # Review and approve recommendations
./seo full_pipeline           # Run complete workflow: export → analyze → seo_check
./seo analytics ga4.csv gsc.csv  # Import analytics data
./seo gaps                    # Analyze content gaps
./seo opportunities           # Analyze keyword opportunities
./seo report                  # Generate SEO optimization report
./seo status                  # Show output files status

🏗️ Project Structure

seo/
├── seo                          # Main CLI executable
├── src/seo/                     # Integrated application package
│   ├── __init__.py              # Package initialization
│   ├── cli.py                   # Command-line interface
│   ├── app.py                   # Main application class
│   ├── config.py                # Configuration management
│   ├── exporter.py              # Post export functionality
│   ├── analyzer.py              # AI analysis functionality
│   ├── recategorizer.py         # Recategorization functionality
│   ├── seo_checker.py           # SEO quality checking
│   ├── categories.py            # Category management
│   └── approval.py              # User approval system
├── scripts/                     # Legacy scripts (deprecated)
├── config.yaml                  # YAML configuration
├── .env                         # Environment variables
├── .env.example                 # Template
├── requirements.txt             # Dependencies
├── output/                      # Generated files
└── README.md

📦 Installation

For development/installation:

# Install in development mode
pip install -e .

# Or just use the executable directly
./seo help

🎯 Typical Workflow

1. Export posts from all sites:

   python scripts/seo-cli.py export
   

2. Review exported data in output/reports/

3. Analyze with AI:

   python scripts/seo-cli.py analyze
   

4. Manage categories:

   python scripts/seo-cli.py categories
   

5. Approve recommendations:

   python scripts/seo-cli.py approve output/reports/*.csv
   

6. Execute approved changes manually in WordPress

📊 Output Files

All results are saved in output/reports/:

• all_posts_for_ai_decision_*.csv - All exported posts
• posts_with_ai_recommendations_*.csv - AI analysis results
• category_assignments_*.csv - Category recommendations
• approved_recommendations_*.csv - Approved changes
• rejected_recommendations_*.csv - Rejected changes

🔒 Security

• Credentials stored in .env file (not committed)
• All API calls use secure authentication
• Read-only operations by default
• Manual approval required for all changes

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

📄 License

MIT License - see LICENSE file for details.

🆘 Support

For support, please open an issue in the repository or contact the maintainers.

---

Made with ❤️ for better SEO automation