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

Find better keyword opportunities faster.

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

Start in 30 seconds Full command reference

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.

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.