page-roast

Brutally honest landing-page CRO audits — bring your own Gemini key.

Quick start

# Set your key once
export GEMINI_API_KEY=your_key_here

# Score a page
npx @bilkobibitkov/page-roast https://yoursite.com

# Roast mode — savage summary only
npx @bilkobibitkov/page-roast https://yoursite.com --mode=roast

# A/B compare two pages
npx @bilkobibitkov/page-roast https://a.com --mode=compare --compare-with=https://b.com

# JSON output for piping
npx @bilkobibitkov/page-roast https://yoursite.com --json | jq .scores

Programmatic use

import { roastPage } from '@bilkobibitkov/page-roast';

const result = await roastPage({
  url: 'https://yoursite.com',
  apiKey: process.env.GEMINI_API_KEY!,
  mode: 'score',  // 'score' | 'compare' | 'roast'
});

console.log(result.scores?.total_score);   // 72
console.log(result.scores?.grade);         // "B"
console.log(result.roastLines);            // [roast, fix1, fix2, fix3, edge]

CLI flags

| Flag | Default | Notes | |---|---|---| | --gemini-key=<key> | env | Overrides env vars | | --mode=score\|compare\|roast | score | Audit mode | | --compare-with=<url2> | — | Required for --mode=compare | | --json | false | Machine-readable output | | --no-color | false | Disable color | | --quiet | false | Suppress progress messages | | --help | — | Show usage |

BYOK env vars

Checked in this order:

| Var | Notes | |---|---| | BILKO_PAGE_ROAST_API_KEY | Most specific — use to scope a key to this tool | | GEMINI_API_KEY | Standard Google AI Studio key | | GOOGLE_API_KEY | Fallback | | --gemini-key=<key> | CLI flag overrides all env vars |

Scoring system

100 points across 4 sections (25 each):

• Hero Section — headline clarity, subheadline, CTA visibility, visual hierarchy
• Social Proof — testimonials, trust logos, quantified proof, risk reversal
• Clarity & Persuasion — 5-second test, benefits over features, readability, objection handling
• Conversion Architecture — CTA frequency, friction reduction, urgency/scarcity, page speed signals

Grade scale: A+ (90–100) → F (0–39)

Security

The page fetcher has SSRF protection: blocks localhost, all private IPv4 ranges (10.x, 172.16–31.x, 192.168.x, 169.254.x), IPv6 loopback, and performs DNS rebinding checks before connecting.

Changelog

See CHANGELOG.md.

License

MIT — see LICENSE.

Built by Bilko. Free, ad-free, no signup. Repo · Issues