keyword-cli

AI-powered SEO keyword research tool for the terminal.

keyword-cli is an open-source Python CLI tool that helps content writers, bloggers, and SEO specialists research keywords directly from the command line. It gathers suggestions from multiple sources, analyzes search intent, scores difficulty and opportunity, clusters related terms, and exports reports — all without leaving your terminal.

Features

• Multi-source keyword gathering — Google Autocomplete, Related Searches, People Also Ask, Wikipedia, Reddit, Bing, DuckDuckGo, and YouTube
• Search intent classification — Rule-based detection of Informational, Navigational, Commercial, and Transactional intent
• Difficulty & opportunity scoring — Estimate keyword competitiveness
• Keyword clustering — Group related keywords by topic/theme
• Long-tail keyword generation — Expand seed keywords into hundreds of variations
• Trend analysis — Determine keyword direction (rising/stable/declining)
• Multiple export formats — CSV, JSON, Markdown, and Excel (.xlsx)
• Local caching — Disk-based cache with configurable TTL
• Configurable — Language, country, provider selection, and more via config.toml

Installation

Requirements

• Python 3.11 or higher

Install via pip

pip install keyword-cli

Install from source (development)

git clone https://github.com/minggo-commits/keyword-cli.git
cd keyword-cli
pip install -e .

Verify installation

keyword doctor

Quick Start

# Get keyword suggestions with analysis
keyword suggest "content marketing"

# Get just autocomplete suggestions
keyword autocomplete "SEO tools"

# Export to a spreadsheet
keyword suggest "digital marketing" --export report --format xlsx

# Check system health
keyword doctor

Usage

Global Options

Option	Description
--version, -V	Show version and exit
--help	Show help message and exit
--install-completion	Install shell completion
--show-completion	Show shell completion

---

1. keyword suggest — Full keyword analysis

Gather keyword suggestions from all enabled providers, classify intent, score difficulty/opportunity, and display results in a table.

# Basic usage
keyword suggest "digital marketing"

# Use specific providers only
keyword suggest "SEO" --provider google_autocomplete --provider wikipedia

# Export results
keyword suggest "content strategy" --export report --format csv
keyword suggest "content strategy" --export report --format json
keyword suggest "content strategy" --export report --format xlsx
keyword suggest "content strategy" --export report --format md

# Show keyword clusters
keyword suggest "web design" --clusters

# Limit displayed results (default: 50)
keyword suggest "python programming" --limit 20

# Bypass cache
keyword suggest "machine learning" --no-cache

Options:

Option	Description
--provider, -p	Specific providers to use (can be repeated)
--export, -e	File path for export (without extension)
--format, -f	Export format: csv, json, md, xlsx
--clusters, -c	Show keyword clusters
--limit, -l	Max keywords to display (default: 50)
--no-cache	Bypass cached results

---

2. keyword autocomplete — Autocomplete suggestions

Fetch autocomplete suggestions from a single source.

# Google autocomplete (default)
keyword autocomplete "content marketing"

# Bing autocomplete
keyword autocomplete "SEO tools" --source bing

# DuckDuckGo
keyword autocomplete "digital marketing" --source duckduckgo

# YouTube
keyword autocomplete "python tutorial" --source youtube

# Limit results
keyword autocomplete "best laptops" --limit 10

Options:

Option	Description
--source, -s	Autocomplete source: google, bing, duckduckgo, youtube (default: google)
--limit, -l	Max suggestions to display (default: 20)
--no-cache	Bypass cached results

---

3. keyword questions — People Also Ask

Fetch "People Also Ask" questions from Google SERP.

keyword questions "SEO tools"
keyword questions "keyword research" --limit 10
keyword questions "content marketing" --no-cache

Options:

Option	Description
--limit, -l	Max questions to display (default: 15)
--no-cache	Bypass cached results

---

4. keyword related — Related searches

Fetch related search terms from Google.

keyword related "keyword research"
keyword related "web development" --limit 15

Options:

Option	Description
--limit, -l	Max related searches to display (default: 20)
--no-cache	Bypass cached results

---

5. keyword clusters — Keyword clustering

Group keywords by topic/theme into clusters.

keyword clusters "SEO"
keyword clusters "digital marketing" --min-size 3
keyword clusters "web design" --provider google_autocomplete --provider wikipedia

Options:

Option	Description
--min-size, -m	Minimum cluster size (default: 2)
--provider, -p	Specific providers to use (can be repeated)
--no-cache	Bypass cached results

---

6. keyword trend — Trend analysis

Analyze keyword trend direction (rising, stable, or declining) based on autocomplete indicators.

keyword trend "python programming"
keyword trend "AI" --months 6

Options:

Option	Description
--months, -m	Lookback period in months (default: 12)
--no-cache	Bypass cached results

---

7. keyword longtail — Long-tail keywords

Generate long-tail keyword variations from a seed keyword.

keyword longtail "SEO tools"
keyword longtail "content marketing" --limit 20

Options:

Option	Description
--limit, -l	Max long-tail keywords to display (default: 30)
--no-cache	Bypass cached results

---

8. keyword export — Format conversion

Convert keyword data from JSON (previously exported via keyword suggest --format json) to other formats.

# JSON to CSV
keyword export results.json -o report.csv -f csv

# JSON to Excel
keyword export results.json -o report.xlsx -f xlsx

# JSON to Markdown
keyword export results.json -o report.md -f md

Arguments:

Argument	Description
input_file	Input JSON file path (from keyword suggest --format json)

Options:

Option	Description
--output, -o	Output file path (required)
--format, -f	Output format: csv, json, md, xlsx

---

9. keyword config — Configuration

View, modify, or reset CLI configuration.

# Show current configuration
keyword config show

# Set a configuration value
keyword config set --key language --value id
keyword config set --key country --value id
keyword config set --key cache_ttl_hours --value 48
keyword config set --key verbose --value true

# Reset to defaults
keyword config reset

Arguments:

Argument	Description
action	Action: show, set, or reset

Options (for set action):

Option	Description
--key, -k	Config key: language, country, cache_ttl_hours, timeout_seconds, max_retries, verbose
--value, -v	Config value

Config file location:

• Windows: C:\Users\<USER>\AppData\Local\keyword-cli\keyword-cli\config.toml
• Linux: ~/.config/keyword-cli/config.toml
• macOS: ~/Library/Application Support/keyword-cli/config.toml

---

10. keyword cache — Cache management

View statistics or clear the local keyword cache.

# View cache stats
keyword cache stats

# Clear all cached data
keyword cache clear

Arguments:

Argument	Description
action	Action: stats or clear

---

11. keyword doctor — System diagnostics

Run system health checks to verify that everything is working properly.

keyword doctor

# Also test internet connectivity
keyword doctor --connectivity

Options:

Option	Description
--connectivity, -c	Test internet connectivity to external services

Data Providers

Provider	Source	Used By
Google Autocomplete	suggestqueries.google.com	suggest, autocomplete, trend
Google Related Searches	google.com/search HTML	suggest, related, clusters
Google People Also Ask	google.com/search HTML	suggest, questions, clusters
Wikipedia	en.wikipedia.org/w/api.php	suggest, clusters
Reddit	reddit.com/search.json	suggest, clusters
Bing	api.bing.com/osjson.aspx	suggest, autocomplete
DuckDuckGo	duckduckgo.com/ac/	suggest, autocomplete
YouTube	suggestqueries.google.com (yt ds)	suggest, autocomplete

Intent Classification

Keyword intent is classified using rule-based heuristics:

Intent	Description	Examples
Informational	Seeking knowledge or answers	"what is SEO", "how to write a blog post"
Navigational	Looking for a specific site	"facebook login", "github docs"
Commercial	Research before purchase	"best laptops 2025", "X vs Y review"
Transactional	Ready to buy or take action	"buy running shoes", "discount code"

Difficulty & Opportunity Scores

• Difficulty (0-100): Higher = harder to rank for (competitive). Based on keyword length, word count, intent, and commercial indicators.
• Opportunity (0-100): Higher = more potential. Inversely related to difficulty, with bonuses for long-tail and question-based keywords.

Export Formats

Format	Extension	Description
CSV	.csv	UTF-8 BOM encoded, compatible with Excel
JSON	.json	Complete data structure including metadata and clusters
Markdown	.md	Formatted report with tables and sections
Excel	.xlsx	Multi-sheet workbook (Keywords, Summary, Clusters)

Caching

Results are cached locally to avoid redundant network requests and improve performance.

• Location: Platform-specific cache directory
  • Windows: C:\Users\<USER>\AppData\Local\keyword-cli\keyword-cli\Cache
  • Linux: ~/.cache/keyword-cli/
  • macOS: ~/Library/Caches/keyword-cli/
• TTL: 24 hours by default (configurable via config set --key cache_ttl_hours)
• Bypass: Use --no-cache flag on any command

Shell Completion

# Install shell completion
keyword --install-completion

# View completion script
keyword --show-completion

Development

Setup

git clone https://github.com/minggo-commits/keyword-cli.git
cd keyword-cli
pip install -e ".[dev]"

Run tests

# Run all 159+ tests
pytest

# Run with coverage
pytest --cov=keyword_cli --cov-report=term-missing

# Run a specific test file
pytest tests/test_intent.py -v

# Run a specific test
pytest tests/test_cache.py::TestKeywordCache::test_cache_with_colons_in_key -v

Lint and format code

ruff check src/
ruff format src/

Type checking

mypy src/

Known Fixes & Compatibility

Windows file name compatibility

The CLI uses colon-separated cache keys (e.g. google_autocomplete:keyword:en:us). On Windows, colons are invalid in file names. The cache module automatically sanitizes all platform-invalid characters (:, <, >, ", |, ?, *) by replacing them with underscores. This fix ensures the tool works correctly on Windows without any configuration changes.

Project Structure

keyword-cli/
├── pyproject.toml              # Project configuration and dependencies
├── README.md                   # This file
├── src/keyword_cli/
│   ├── __init__.py             # Package init with version
│   ├── __main__.py             # `python -m keyword_cli` entry point
│   ├── main.py                 # CLI app and command registration
│   ├── models.py               # Pydantic data models
│   ├── config.py               # TOML config management
│   ├── cache.py                # Disk-based caching
│   ├── providers/
│   │   ├── __init__.py         # Base provider class
│   │   ├── google_autocomplete.py
│   │   ├── google_related.py
│   │   ├── google_questions.py
│   │   ├── wikipedia.py
│   │   ├── reddit.py
│   │   ├── bing.py
│   │   ├── duckduckgo.py
│   │   └── youtube.py
│   ├── analysis/
│   │   ├── __init__.py
│   │   ├── intent.py           # Intent classification
│   │   ├── scoring.py          # Difficulty/opportunity scoring
│   │   ├── long_tail.py        # Long-tail generation
│   │   └── clustering.py       # Keyword clustering
│   ├── export/
│   │   ├── __init__.py
│   │   ├── base.py             # Base exporter and utilities
│   │   ├── csv_export.py
│   │   ├── json_export.py
│   │   ├── markdown_export.py
│   │   └── excel_export.py
│   └── cli/
│       ├── __init__.py
│       ├── suggest.py
│       ├── autocomplete.py
│       ├── questions.py
│       ├── related.py
│       ├── clusters.py
│       ├── trend.py
│       ├── longtail.py
│       ├── export_cmd.py
│       ├── config_cmd.py
│       ├── cache_cmd.py
│       └── doctor.py
└── tests/

License

MIT License — see LICENSE for details.