# CLI reference

TurboSEO provides four commands for content analysis.

## Global options

```bash
turboseo --version    # Show version
turboseo --help       # Show help
```

## Commands

### turboseo check

Check content for AI writing patterns.

```bash
turboseo check <file> [options]
```

**Arguments:**
- `<file>` - Path to content file (required)

**Options:**
- `--strict` - Use stricter scoring thresholds
- `--json` - Output as JSON

**Output:**
- Grade (A-F) and score (0-100)
- Issues table with line numbers
- Suggestions for each issue
- Summary by category

**Examples:**

```bash
# Basic check
turboseo check article.md

# Strict mode (higher penalties)
turboseo check article.md --strict

# JSON output
turboseo check article.md --json
```

---

### turboseo analyze

Full SEO analysis with weighted scoring.

```bash
turboseo analyze <file> [options]
```

**Arguments:**
- `<file>` - Path to content file (required)

**Options:**
- `-k, --keyword TEXT` - Primary keyword
- `-s, --secondary TEXT` - Secondary keywords (can repeat)
- `--title TEXT` - Meta title for analysis
- `--description TEXT` - Meta description for analysis
- `--json` - Output as JSON

**Score weights:**
| Category | Weight |
|----------|--------|
| Human Writing | 25% |
| Keywords | 20% |
| Content | 20% |
| Readability | 15% |
| Meta Tags | 10% |
| Structure | 10% |

**Examples:**

```bash
# Basic analysis
turboseo analyze article.md

# With primary keyword
turboseo analyze article.md -k "podcast hosting"

# With primary and secondary keywords
turboseo analyze article.md -k "podcast hosting" -s "best podcast host" -s "podcast platforms"

# With meta tags
turboseo analyze article.md -k "podcast hosting" \
  --title "Best Podcast Hosting 2024" \
  --description "Compare top podcast hosting platforms..."
```

---

### turboseo readability

Analyze content readability metrics.

```bash
turboseo readability <file> [options]
```

**Arguments:**
- `<file>` - Path to content file (required)

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

**Metrics:**

| Metric | Target | Description |
|--------|--------|-------------|
| Flesch Reading Ease | 60-70 | Higher = easier to read |
| Flesch-Kincaid Grade | 8-10 | US grade level |
| Gunning Fog Index | - | Years of education needed |
| SMOG Index | - | Simple Measure of Gobbledygook |
| Avg Sentence Length | 15-20 words | Shorter is usually better |
| Passive Voice | <20% | Active voice preferred |

**Examples:**

```bash
# Basic readability
turboseo readability article.md

# JSON output
turboseo readability article.md --json
```

---

### turboseo keywords

Analyze keyword usage and placement.

```bash
turboseo keywords <file> -k <keyword> [options]
```

**Arguments:**
- `<file>` - Path to content file (required)

**Options:**
- `-k, --keyword TEXT` - Primary keyword (required)
- `-s, --secondary TEXT` - Secondary keywords (can repeat)
- `-d, --target-density FLOAT` - Target density percentage (default: 1.5)
- `--json` - Output as JSON

**Analysis includes:**
- Keyword density vs target
- Critical placements check:
  - H1 (title)
  - First 100 words
  - Conclusion
  - H2 headings
- Section distribution
- Keyword stuffing risk

**Stuffing risk levels:**
| Level | Meaning |
|-------|---------|
| None | Keyword usage is natural |
| Low | Slightly higher than optimal |
| Medium | May appear forced |
| High | Clear over-optimization |

**Examples:**

```bash
# Basic keyword analysis
turboseo keywords article.md -k "podcast hosting"

# With custom target density
turboseo keywords article.md -k "podcast hosting" -d 2.0

# With secondary keywords
turboseo keywords article.md -k "podcast hosting" \
  -s "podcast platform" -s "audio hosting"
```

## Exit codes

| Code | Meaning |
|------|---------|
| 0 | Success |
| 1 | Error (file not found, invalid options) |

## Piping and scripting

Commands work well in scripts:

```bash
# Process multiple files
for f in drafts/*.md; do
  echo "=== $f ==="
  turboseo check "$f"
done

# Extract scores with jq
turboseo check article.md --json | jq '.score'

# Fail CI if score too low
score=$(turboseo check article.md --json | jq '.score')
if [ "$score" -lt 80 ]; then
  echo "Human writing score too low: $score"
  exit 1
fi
```
