Web-first • No logins • No API keys • Python stdlib only

Python keyword generator CLI for practical SEO research.

kwg helps SEOs, founders, and marketers discover keyword ideas from real public web signals, then score, cluster, and export them into actionable topic groups and content briefs.

Start in 30 seconds Full command reference Read the articles

Quick run copy/paste

python kwg.py pop "vps hosting" --top 200 --clusters 8 --format report --out ./kwg_out

Writes keywords.json, keywords.csv, clusters.json, and report.md

Data Sources

Autocomplete, Trends, Reddit, SERP

Intent Signals

Question, commercial, troubleshooting

Outputs

TXT, JSON, CSV, MD, Report

Scaling

Cache, rate limit, bundles, CI-friendly

Built for practical SEO workflows

Use kwg for content planning, cluster mapping, competitor SERP analysis, and long-tail keyword expansion. Results are directional, transparent, and fast to iterate.

Features

Everything is optional and controlled with explicit CLI flags.

Web-first keyword discovery

Collect keyword signals from live public endpoints, not stale static keyword lists.

Explainable scoring model

Source weighting, recurrence, weakness proxies, and intent-aware scoring in one ranking system.

Variants engine

Generate deterministic long-tail expansions for question, commercial, compare, and platform use cases.

Keyword clustering

Create grouped topic clusters and publishable reports for content planning and SEO briefs.

Fault-tolerant fetching

Retries, source-level failure isolation, and graceful warnings when a provider blocks requests.

Automation ready

Stdlib-only Python design makes kwg easy to run in scripts, cron jobs, and CI pipelines.

Quick Start

Use these commands to run keyword generation, expansion, and scoring right away.

Install + Help

git clone https://github.com/zaunere/kwg
cd kwg
python kwg.py --help

Top keyword ideas

python kwg.py pop "keyword clustering" --top 150

JSON output for pipelines

python kwg.py pop "keyword research tool" --top 250 --format json

Offline variant generation

python kwg.py pop "technical seo" --variants all --variants-only --format md

SEO Use Cases

KWG is optimized for modern keyword research and topical authority workflows.

Topical map creation

Generate parent terms, long-tail modifiers, and intent groupings to build content hubs and supporting pages.

SERP opportunity finding

Use SERP domain diversity and UGC-heavy results as competition proxies to spot lower-friction ranking targets.

Programmatic content briefs

Export JSON/CSV bundles and feed them into your SEO dashboard, CMS tooling, or internal briefing workflow.

Articles and Research

Internal guides and essays connected to keyword research, search data, browser behavior, AI workflows, and platform power.

Search data

The Referer Trick: How Google Hides Search Keywords

How search query keywords disappear from website analytics, why Google still sees the data, and how that creates analytics vendor lock-in.

Read the article Browsers and AI

Browsers Were Designed to Render Pages - Not Understand Them

Why modern web pages are easy for browsers to render but difficult for AI systems to understand as clean information.

Read the essay AI automation

Visual Macro AI Copilot Architecture Blueprint

A system design for screen-region selection, OCR, LLM decisions, and human-controlled GUI workflow automation.

View the blueprint

Why these topics belong together

KWG works with public search signals. The supporting essays examine the infrastructure around those signals: how browsers render information, how platforms control analytics visibility, and how AI tools can act on screen-level context.

Documentation

Complete command reference for kwg, synchronized with docs.md.

KWG Full Documentation

kwg is a web-first keyword discovery CLI with no login, no API keys, and no external Python dependencies.

Overview

Discover keywords from autocomplete, trends, Reddit, and SERP sources.
Deduplicate and score terms with transparent heuristics.
Generate keyword variants and optional topical clusters.
Export machine-friendly and report-friendly output formats.

Installation

git clone https://github.com/zaunere/kwg
cd kwg
python kwg.py --help

Python 3.10+ is recommended.

Core Commands

pop: full pipeline (fetch, expand, score, output).

python kwg.py pop "vps hosting" --top 200 --format report

expand: candidate generation only (no scoring).

python kwg.py expand "vps hosting" --limit 500 --format json

score: score existing term lists.

cat terms.txt | python kwg.py score --from stdin --top 200
python kwg.py score --from file --file terms.txt --format csv

Source Controls

--sources autocomplete,trends,reddit,serp
--geo US
--hl en
--kl us-en

SERP Feature Toggles

--serp-related / --no-serp-related
--serp-snippets / --no-serp-snippets
--serp-freshness / --no-serp-freshness
--serp-ugc / --no-serp-ugc
--serp-weakness / --no-serp-weakness
--serp-ngrams / --no-serp-ngrams

Variants Engine

--variants none|basic|all|custom
--variants-packs question,commercial,compare,local,platform,opensource,howto
--variants-max-per-term N
--variants-max-total N
--variants-seed-only
--variants-to-sources
--variants-only
--variants-include-original / --no-variants-include-original

Scoring Model

Source presence and multi-source bonus.
Trends recurrence across history windows.
SERP weakness, UGC, and freshness proxy boosts.
Length, intent, and low-quality penalties.

Use --explain to inspect reason-level scoring output.

Clustering and Reports

python kwg.py pop "vps hosting" --top 200 --clusters 8 --format report
python kwg.py pop "vps hosting" --top 200 --clusters 8 --out ./kwg_out

Outputs can include clusters.json and report.md.

Output Formats

--format txt|json|csv|md|report
--out ./kwg_out

Caching and Rate Limiting

--cache-dir ~/.kwg/cache
--cache-ttl 21600
--rate-limit 0.6

Fault Tolerance

HTTP retries with backoff for transient failures.
Per-source warning and continue behavior.
A blocked source (for example, Reddit 403) no longer crashes the run.

Troubleshooting

python kwg.py pop "vps hosting" --sources autocomplete,trends,serp
python kwg.py pop "vps hosting" --sources autocomplete --rate-limit 1.0
python kwg.py pop "vps hosting" --variants all --variants-only

Roadmap

Config bootstrap command
Additional web signal sources
Optional embeddings-based clustering

Project Links

Official links for docs, source code, and site reference.

Repository

github.com/zaunere/kwg

Issues, source code, and contribution workflow.

Website

keywordgenerative.com

Landing page, full docs, and quick command reference.