@warpmetrics/blog-seo

Self-improving technical blog engine. Generates code-heavy blog posts, tracks search performance via Google Search Console, learns what works, and writes better content each cycle.

Setup

npm install
cp .env.example .env  # Add your API keys

Environment variables

OPENAI_API_KEY=sk-...
WARPMETRICS_API_KEY=wm_...

Configuration

Create blog-seo.config.json in the directory you'll run the CLI from:

{
  "domain": "warpmetrics.com",
  "siteUrl": "sc-domain:warpmetrics.com",
  "outputDir": "./src/content/blog",
  "manifest": "./blog-seo.json"
}

| Field | Description | |-------|-------------| | domain | Your domain. Used to fetch product context from llms-full.txt / llms.txt | | siteUrl | Google Search Console site URL (usually sc-domain:yourdomain.com) | | outputDir | Where generated markdown files are written | | manifest | Path to the manifest file that tracks generated posts |

Product context

blog-seo fetches product context to ground generated content in accurate information. It looks for:

1. https://{domain}/llms-full.txt (preferred)
2. https://{domain}/llms.txt (fallback)

These follow the llms.txt convention — a plain text file describing your product, APIs, features, and pricing. When present, this context is included in every generation prompt so the LLM uses real API names and features instead of hallucinating.

If neither file exists, posts are generated without product context.

Commands

blog-seo auth

Authenticate with Google Search Console via OAuth.

npx blog-seo auth

Saves credentials to .gsc-credentials.json.

blog-seo seed

Generate initial blog posts from built-in seed topics. No GSC data needed.

npx blog-seo seed --max 3

| Flag | Default | Description | |------|---------|-------------| | --max | 5 | Maximum posts to generate | | --output | from config | Output directory | | --max-retries | 2 | Retries per post on validation failure |

blog-seo analyze

Display GSC performance for existing blog posts.

npx blog-seo analyze --days 30

blog-seo run

Full flywheel: Feedback → Learn → Plan → Generate.

npx blog-seo run --max-new 3 --max-rewrites 2

| Flag | Default | Description | |------|---------|-------------| | --max-new | 3 | Max new posts per run | | --max-rewrites | 2 | Max rewrites of underperformers | | --min-days | 14 | Days before tracking a post | | --min-impressions | 50 | Min impressions for feedback | | --max-retries | 2 | Retries per post on validation failure | | --output | from config | Output directory | | --manifest | from config | Manifest file path |

How it works

Each run cycle executes four phases:

1. Feedback — Fetches GSC metrics for tracked posts. Classifies each as High Traffic, Improved, Stagnant, or Declining.

2. Learn — Analyzes high-performing posts to find patterns (topic, structure, code density). Updates generation prompts with learned patterns.

3. Plan — Identifies topic gaps from GSC query data (queries with impressions but no matching content). Selects underperformers for rewrites.

4. Generate — Writes new posts or rewrites underperformers. Each post goes through a two-step process (outline → full post) and is validated for structure, code correctness, quality, and SEO before being written.

Every cycle creates a WarpMetrics run with outcomes and a "Continue Optimization" act that links to the next run, forming an unbroken improvement chain.

Generated post format

Posts are markdown with YAML frontmatter:

---
title: "How to Track LLM API Costs"
description: "Track OpenAI, Anthropic, and Cohere costs..."
date: 2026-02-15
author: "blog-seo"
keywords: ["llm costs", "api cost tracking"]
generated: true
---

# How to Track LLM API Costs

[code-heavy content]

The generated: true field distinguishes machine-generated posts from human-written ones.

Manifest

blog-seo.json tracks which posts were generated and their baselines:

{
  "tracking-llm-costs": {
    "slug": "tracking-llm-costs",
    "title": "How to Track LLM API Costs",
    "generatedAt": "2026-02-15T10:00:00Z",
    "runId": "wm_run_xxx",
    "targetKeywords": ["track llm costs"],
    "version": 1,
    "baseline": { "ctr": null, "position": null, "impressions": 0 }
  }
}

Validation

Every generated post passes four validators before being written:

1. Structure — Frontmatter, H1, 3+ H2 sections, 2+ code blocks, 800-3000 words
2. Code — Matched code fences, no truncated snippets
3. Quality — LLM-scored 1-10 (must score 7+)
4. SEO — Title contains keyword, description 140-160 chars, H2 contains keyword