SEO

# SEO

Track where you rank in Google, monitor position changes, and discover keyword opportunities to grow organic traffic.

## When to Use
- User wants to track how their keywords rank in Google search
- User needs to discover new keyword opportunities for content creation
- User wants to monitor position changes for tracked keywords over time
- User is planning blog content and needs keyword data to prioritize topics

## How It Connects
- **Blog** → Use keyword opportunities to inform blog article topics. Track rankings for published content.
- **Analytics** → Correlate keyword ranking changes with traffic trends.
- **AI Visibility** → SEO tracks traditional search engines (Google). For AI platform visibility (ChatGPT, Claude, Gemini), use the ai-visibility skill instead.
- **Branding** → Brand positioning and category inform keyword strategy.
- **Documents** → Save keyword research findings as document pages for reference.

## Quick Start

Track keywords you care about:
```bash
clawpow seo track "fulfillment software,ecommerce logistics" --json
```

## Commands

### Track Keywords
```bash
clawpow seo track "fulfillment software" --json
clawpow seo track "fulfillment software,ecommerce logistics,3pl pricing" --json
```
Add keywords to your SEO watchlist. Position and market data are collected automatically via weekly cron.

**Options:**
- `<keywords>` (required, positional) -- Comma-separated keywords to track
- `--json` -- Output as JSON

**Returns:** `{"tracked": ["fulfillment software"], "alreadyTracked": []}`

### Untrack Keywords
```bash
clawpow seo untrack "3pl pricing" --json
```
Remove keywords from your watchlist and delete their position history.

**Options:**
- `<keywords>` (required, positional) -- Comma-separated keywords to untrack
- `--json` -- Output as JSON

**Returns:** `{"untracked": ["3pl pricing"], "notFound": []}`

### SEO Snapshot
```bash
clawpow seo snapshot --json
clawpow seo snapshot --days 7 --json
```
View aggregate search performance (clicks, impressions, CTR, avg position) and current tracked keyword positions with market data.

**Options:**
- `--days <n>` -- Time range in days (default: 30)
- `--json` -- Output as JSON

**Returns:** Aggregate KPIs + tracked keywords with position, volume, difficulty, intent, and position history.

### Find Opportunities
```bash
clawpow seo opportunities find --json
clawpow seo opportunities find "fulfillment,3pl" --json
clawpow seo opportunities find "fulfillment" --limit 50 --json
```
Discover keyword opportunities. When called **without keywords**, automatically generates seed keywords from your brand positioning and website content using AI, then expands them via DataForSEO. When called **with keywords**, uses your manual seeds directly.

**Options:**
- `[keywords]` (optional, positional) -- Comma-separated seed keywords. Omit to auto-generate from brand.
- `--limit <n>` -- Max keywords to return (default: 50)
- `--json` -- Output as JSON

**Returns:** `{"found": 43, "new": 38, "updated": 5, "source": "brand"}`. This is a queued operation that consumes credits. The `source` field indicates whether seeds came from `"brand"` (auto-generated) or `"manual"` (user-provided).

**Prerequisites for brand mode:** Brand must have positioning data set. Run `clawpow branding positioning update` first. A website URL in brand settings provides additional signal but is not required.

### List Opportunities
```bash
clawpow seo opportunities list --json
```
View all discovered keyword opportunities sorted by search volume.

**Options:**
- `--json` -- Output as JSON

**Returns:** Array of `{keyword, volume, difficulty, intent, cpc, seedKeyword, discoveredAt, updatedAt}`

## Output Format

All commands support `--json` for structured output. Without `--json`, output is human-readable.

## Important Notes

- Always use `--json` for machine-parseable output
- Track/untrack and snapshot are free operations
- Tracking a keyword automatically removes it from opportunities
- Position data comes from Google Search Console (real data) with DataForSEO fallback for deep rankings
- Market data (volume, difficulty, intent) comes from DataForSEO
- Positions are updated automatically by a weekly cron job
- `opportunities find` is a paid operation (consumes credits)
- `opportunities list` is a free read query
- SEO requires a connected Google Search Console property