HeadHunt-CLI 🎯

The terminal-first SEO metadata hunter. Scrape, score, and audit any website's SEO health directly from the command line.

✨ Features

🔍 Comprehensive SEO Extraction

• Basic Metadata — title, meta description, canonical, robots, viewport, charset, language
• Open Graph — full og: tag detection for social sharing
• Twitter Cards — twitter: card, title, description, image
• Schema.org — JSON-LD & Microdata parsing with type detection
• Technical SEO — doctype, hreflang, pagination, sitemap, RSS, AMP, manifest

📊 Intelligent Scoring Engine

• 100-point SEO score across 14 weighted categories
• Letter grade (A+ to F) with contextual summary
• Priority-ranked recommendations with impact & effort estimates

🔗 Link & Content Analysis

• Internal vs external link classification
• Nofollow, sponsored, UGC rel attribute detection
• Empty anchor text detection
• Heading hierarchy validation (H1–H6) with skip detection
• Image alt-text coverage & lazy-loading audit
• Word count, paragraph count & keyword density estimation

🛡️ Security & Performance Signals

• HTTPS, HSTS, CSP, X-Frame-Options, X-Content-Type-Options
• Render-blocking script detection
• HTML payload size & fetch time analysis
• Estimated total page weight

📈 Professional Output Modes

• Terminal Report — beautifully formatted with color-coded scores
• JSON Export — full structured data for pipelines (--json, --json-file)
• Score-Only — CI-friendly single-line output (--score-only)
• Deep Audit — verbose recommendations with impact/effort badges (--audit)
• Side-by-Side Comparison — compare two URLs (--compare)

🚀 Installation

Via npm (recommended)

npm install -g headhunt

Then run from anywhere:

headhunt https://example.com

Via npx (no install)

npx headhunt https://example.com

From Source

git clone https://github.com/imharris24/HeadHunt.git
cd HeadHunt
npm install
chmod +x headhunt.js
node headhunt.js https://example.com

📖 Usage

Basic Scan

headhunt https://example.com

Output Modes

| Flag | Description | |------|-------------| | --json | Print full raw JSON to stdout | | --json-file | Save JSON report to seo-report-<hostname>-<timestamp>.json | | --score-only | Print Score: 78/100 Grade: B+ (CI-friendly) | | --audit | Show full recommendations with impact & effort badges |

# CI pipeline check
headhunt --score-only https://example.com

# Deep audit with actionable fixes
headhunt --audit https://example.com

# Export full JSON for further processing
headhunt --json-file https://example.com

Skip Analysis (Faster)

| Flag | Description | |------|-------------| | --no-links | Skip link analysis | | --no-images | Skip image analysis |

headhunt --no-links --no-images https://example.com

Compare Two URLs

headhunt https://site-a.com --compare https://site-b.com

Generates a side-by-side comparison table with a declared winner.

📋 Example Output

════════════════════════════════════════════════════════════════════

  TARGET   https://example.com
  SCANNED  5/23/2026, 10:30:00 AM
  PLATFORM WordPress

────────────────────────────────────────────────────────────────────

  OVERALL SEO SCORE

    ██████████████████████████████░░░░░░░░░░░░░░░░░░░░░░░░░░  78/100  Grade: B+

  Solid SEO signals present. Primary opportunities in Image Optimization
  and Structured Data — addressing these could meaningfully boost rankings.

────────────────────────────────────────────────────────────────────

  CATEGORY BREAKDOWN

  ✓ Title Tag              ████████████████░░░░░░  15/15
  ✓ Meta Description       ████████████░░░░░░░░░░  10/12
  ~ Heading Structure      ████████░░░░░░░░░░░░░░   6/10
  ✓ Canonical URL          █████░░░░░░░░░░░░░░░░░   5/5
  ...

  QUICK STATS

  Title                        "Example Domain — A pla..." (47c)
  Meta Description             155 chars
  Canonical                    Present
  H1 Tags                      1 (ideal)
  Word Count                   ~1,240 words (7 min read)
  Images                       12 total, 67% have alt
  HTTPS                        Yes
  Response Time                420ms

  RECOMMENDATIONS  (7 items)

  01. ● HIGH      Image Optimization
      Issue: 4 image(s) missing alt text (33% uncovered).
      Fix:  Add descriptive alt attributes to all meaningful images...

  02. ● MEDIUM    Structured Data
      Issue: No structured data (schema.org) found.
      Fix:  Implement JSON-LD structured data appropriate to your content type...

════════════════════════════════════════════════════════════════════

🏗️ Architecture

HeadHuntSEO
├── Fetch Engine       → axios with custom headers & redirect handling
├── Parser Layer       → cheerio for fast server-side HTML parsing
├── Extractors         → modular metadata, schema, link, image, content
├── Scoring Engine     → weighted rubric across 14 SEO categories
├── Recommendations    → priority-ranked, impact/effort tagged advice
└── Display Engine     → ANSI-colored terminal reports & JSON serializers

🔧 Development

# Clone & setup
git clone https://github.com/imharris24/HeadHunt.git
cd HeadHunt
npm install

# Run locally
node headhunt.js https://example.com --audit

# Run tests
npm test

# Lint
npm run lint

🗺️ Roadmap

| Feature | Status | |---------|--------| | Core metadata extraction | ✅ | | Intelligent scoring engine | ✅ | | Terminal reporting | ✅ | | JSON export modes | ✅ | | URL comparison | ✅ | | npm global install | ✅ | | JavaScript rendering (Puppeteer/Playwright) | 🚧 | | Bulk URL processing | 🚧 | | Broken link checking | 🚧 | | CSV / Markdown export | 🚧 | | Proxy & bot-protection bypass | 🚧 | | Core Web Vitals integration | 🚧 |

🤝 Contributing

Contributions are welcome! Please open an issue or submit a pull request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License — see the LICENSE file for details.

🐛 Support

Found a bug or have a feature request? Please open an issue.

Built with 💻 by imharris24