Metadata-Version: 2.4
Name: keyword-cli
Version: 0.1.0
Summary: AI-powered SEO keyword research CLI tool. Generate keyword suggestions, analyze intent, and export reports directly from the terminal.
License: MIT
License-File: LICENSE
Keywords: seo,keyword-research,cli,content-marketing,sem
Author: minggo-commits
Author-email: zanzanakbar5@gmail.com
Requires-Python: >=3.11
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Dist: httpx (>=0.28.0,<0.29.0)
Requires-Dist: openpyxl (>=3.1.0,<4.0.0)
Requires-Dist: platformdirs (>=4.3.0,<5.0.0)
Requires-Dist: pydantic (>=2.10.0,<3.0.0)
Requires-Dist: pydantic-settings (>=2.7.0,<3.0.0)
Requires-Dist: rich (>=13.9.0,<14.0.0)
Requires-Dist: selectolax (>=0.3.0,<0.4.0)
Requires-Dist: tomli (>=2.2.0,<3.0.0) ; python_version < "3.11"
Requires-Dist: tomli-w (>=1.2.0,<2.0.0)
Requires-Dist: typer[all] (>=0.15.0,<0.16.0)
Project-URL: Homepage, https://github.com/minggo-commits/keyword-cli
Project-URL: Repository, https://github.com/minggo-commits/keyword-cli
Description-Content-Type: text/markdown

# 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

```bash
pip install keyword-cli
```

### Install from source (development)

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

### Verify installation

```bash
keyword doctor
```

## Quick Start

```bash
# 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.

```bash
# 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.

```bash
# 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.

```bash
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.

```bash
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.

```bash
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.

```bash
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.

```bash
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.

```bash
# 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.

```bash
# 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.

```bash
# 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.

```bash
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

```bash
# Install shell completion
keyword --install-completion

# View completion script
keyword --show-completion
```

## Development

### Setup

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

### Run tests

```bash
# 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

```bash
ruff check src/
ruff format src/
```

### Type checking

```bash
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](LICENSE) for details.

