# Getting started

This guide walks you through installing TurboSEO and running your first content analysis.

## Requirements

- Python 3.10 or higher
- pip package manager

## Installation

### From PyPI (recommended)

```bash
pip install turboseo
```

### From source (development)

```bash
git clone https://github.com/thijs/turboseo.git
cd turboseo
pip install -e ".[dev]"
```

The `[dev]` extra installs testing and linting tools (pytest, ruff, mypy).

## Verify installation

```bash
turboseo --version
```

You should see the version number (e.g., `turboseo, version 0.2.0`).

## Your first analysis

### Check for AI writing patterns

Create a sample file or use existing content:

```bash
turboseo check article.md
```

Output shows:
- **Grade** (A-F) and **Score** (0-100)
- **Issues table** with line numbers, categories, and suggestions
- **Summary** of issues by category

Example output:

```
╭─────────────────────── Human Writing Check ───────────────────────╮
│ Grade: B | Score: 82/100 | Words: 1,247                          │
╰───────────────────────────────────────────────────────────────────╯
┏━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Line ┃ Category   ┃ Issue                        ┃ Suggestion                            ┃
┡━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ 12   │ vocabulary │ delve                        │ Replace with: explore, examine, look  │
│ 45   │ puffery    │ plays a vital role           │ State the specific impact instead     │
│ 89   │ structural │ In conclusion,               │ Remove the announcement               │
└──────┴────────────┴──────────────────────────────┴────────────────────────────────────────┘

Summary: vocabulary: 1, puffery: 1, structural: 1
```

### Full SEO analysis

For comprehensive analysis including keywords and readability:

```bash
turboseo analyze article.md --keyword "podcast hosting"
```

This analyzes:
- Human writing score (25% weight)
- Keyword usage and placement (20% weight)
- Content length and structure (20% weight)
- Readability metrics (15% weight)
- Meta tags if provided (10% weight)
- Document structure (10% weight)

### Readability analysis

For detailed readability metrics:

```bash
turboseo readability article.md
```

Metrics include:
- Flesch Reading Ease (target: 60-70)
- Flesch-Kincaid Grade Level (target: 8-10)
- Sentence length analysis
- Passive voice detection
- Transition word count

### Keyword analysis

For keyword-specific analysis:

```bash
turboseo keywords article.md -k "podcast hosting"
```

Shows:
- Keyword density and target comparison
- Critical placements (H1, first 100 words, conclusion)
- Section distribution
- Keyword stuffing risk

## JSON output

All commands support `--json` for programmatic use:

```bash
turboseo check article.md --json > results.json
```

## Next steps

- Read [Human Writing Standards](human-writing-standards.md) to understand what patterns are detected
- See [CLI Reference](cli-reference.md) for all command options
- Set up [Claude Code Integration](claude-code-integration.md) for AI-assisted content creation
