cspellfix - Interactive cSpell Dictionary Manager¶

cspellfix [options] [directory]
```bash

### Options

#### Basic Options

- `--help`, `-h`: Show help message
- `--version`, `-v`: Show version
- `--dry-run`: Show what would be done without changes

#### Source Selection

- `--source auto`: Auto-detect (trunk → cspell → scan) [default]
- `--source trunk`: Use `trunk check --filter=cspell`
- `--source cspell`: Use native `cspell` CLI
- `--source scan`: Scan directory for existing words

#### Processing Modes

- `--interactive`, `-i`: Show context and prompt for each word [default]
- `--all`, `-a`: Add all misspelled words without prompting
- `--wizard`, `-w`: Interactive wizard to configure options

#### LLM Integration

- `--llm-prompt`: Generate LLM prompt for human review
- `--llm-auto`: Automated LLM mode (multi-dir if config exists)
- `--batch-apply-cache`: Apply cached batch file to configured directories

#### Configuration Options

- `--no-global`: Ignore global configuration
- `--global-first`: Global config takes precedence [default]
- `--project-first`: Project config takes precedence
- `--review-global`: Review/edit global TOML config
- `--review-project`: Review/edit project TOML config

#### Advanced

- `--batch`: Read commands from stdin
- `--batch-file FILE`: Read batch commands from file
- `--batch-ingest FILE`: Read and clear file after processing
- `--export-os`: Export approved words to OS dictionary
- `--import-os`: Import OS dictionary words
- `--summarize`: Show configuration summary and sync status

## Examples

### Basic Interactive Workflow

```bash
# Start interactive spell checking in current directory
# Shows each misspelled word with context and prompts for action
cspellfix

# Check a specific project directory
# Useful when working on multiple projects
cspellfix ~/projects/my-web-app

# Dry run to see what would be done without making changes
# Safe way to preview potential spelling issues
cspellfix --dry-run
```bash

### Batch Processing Examples

```bash
# Add all misspelled words automatically (dangerous!)
# Only use when you're confident about all suggestions
cspellfix --all

# Use wizard mode for guided configuration
# Helps set up options interactively
cspellfix --wizard
```bash

### Source Selection Examples

```bash
# Use trunk (fastest, if trunk tool is installed)
# Integrates with your existing CI/CD pipeline
cspellfix --source trunk

# Use native cspell CLI (most comprehensive)
# Best for complex spell checking rules
cspellfix --source cspell

# Scan existing dictionary files only
# Quick check without running full spell check
cspellfix --source scan
```bash

### LLM-Assisted Workflow

```bash
# Generate a detailed prompt for AI/LLM review
# Creates comprehensive context about spelling issues
cspellfix --llm-prompt > spelling-review-prompt.md

# [Edit the prompt.md file if needed, then send to AI assistant]
# [AI assistant reviews and suggests batch commands]

# Apply AI-generated recommendations
# Automatically processes the batch file created by AI
cspellfix --batch-apply-cache
```bash

### Multi-Directory Mode

```bash
# First, configure which directories to manage
# Creates a config file for multi-repo spell checking
cat > ~/.config/zshand/cspellfix-dirs.toml << 'EOF'
[dirs]
paths = ["~/.config/zshand", "~/logs/zshand", "~/.cache/zshand"]

[output]
batch_file = "~/.cache/zshand/cspellfix-batch.txt"
EOF

# Process all configured directories automatically
# Uses LLM to generate batch recommendations for all repos
cspellfix --llm-auto
```bash

### Configuration Management

```bash
# Review and edit global configuration
# Manage words that should be accepted everywhere
cspellfix --review-global

# Review and edit project-specific configuration
# Words specific to this project only
cspellfix --review-project

# Force global config to take precedence
# Useful when project config is too restrictive
cspellfix --global-first
```bash

### Advanced Filtering

```bash
# Process from stdin (useful for scripts)
# Pipe misspelled words from other tools
echo "+customword" | cspellfix --batch

# Combine with other tools
# Check only recently changed files
git diff --name-only | xargs -I {} find {} -name "*.md" | cspellfix --batch
```bash

## Configuration

### Global Configuration

Location: `~/.config/zshand/cspell-global.toml`

```toml
# Global approved words and auto-replacements
[words]
# Words to always accept
approved = ["word1", "word2", "word3"]

[replacements]
# Auto-replace patterns
"teh" = "the"
"recieve" = "receive"
"seperate" = "separate"

[patterns]
# Regex patterns to ignore
ignore = ['^\\d+$', '^https?://']
```bash

### Project Configuration

Location: `.cspell-confirmed.toml` (in project root)

```toml
# Project-specific configuration
[words]
approved = ["projectname", "apiendpoint"]

[ignore]
# Files/patterns to skip
files = ["node_modules/**", "*.min.js"]
words = ["skipword1", "skipword2"]
```bash

### Multi-Directory Configuration

Location: `~/.config/zshand/cspellfix-dirs.toml`

```toml
[dirs]
# Directories to process in --llm-auto mode
paths = [
    "~/.config/zshand",
    "~/logs/zshand",
    "~/.cache/zshand"
]

[output]
# Where to save LLM batch files
batch_file = "~/.cache/zshand/cspellfix-batch.txt"
prompt_file = "~/.cache/zshand/cspellfix-prompt.md"
```bash

## Dependencies

### Required

- **cspell** or **trunk**: Spell checking engine
- **zsh**: Shell environment
- **toml** support: Built into modern zsh

### Optional

- **LLM integration**: For --llm-\* options
- **fzf**: Enhanced interactive selection
- **jq**: JSON processing for some sources

## Troubleshooting

### No Misspelled Words Found

**Symptom:** "No misspelled words found"

**Cause:** Source selection or configuration issue

**Fix:**

```bash
# Check available sources
cspellfix --source scan  # See existing words
cspellfix --source cspell  # Try native cspell
cspellfix --source trunk  # Try trunk

# Check configuration
cspellfix --summarize
```bash

### Configuration Not Found

**Symptom:** "Configuration file not found"

**Cause:** Missing or incorrect path

**Fix:**

```bash
# Create global config
mkdir -p ~/.config/zshand
touch ~/.config/zshand/cspell-global.toml

# Edit configuration
cspellfix --review-global
```bash

### LLM Batch File Issues

**Symptom:** "Cannot read batch file" or "Invalid batch format"

**Cause:** Malformed batch file from AI

**Fix:**

```bash
# Check batch file format
cat ~/.cache/zshand/cspellfix-batch.txt

# Expected format:
# +word1
# -word2
# =old:new

# Edit manually if needed
edit ~/.cache/zshand/cspellfix-batch.txt
cspellfix --batch-apply-cache
```bash

### Permission Issues

**Symptom:** "Cannot write to configuration file"

**Cause:** Directory permissions

**Fix:**

```bash
# Fix permissions
chmod u+w ~/.config/zshand/
chmod u+w ~/.config/zshand/cspell-global.toml
```bash

## Performance

- **Single directory**: ~1-5 seconds
- **Multi-directory**: ~10-30 seconds
- **LLM processing**: Variable (depends on AI response time)
- **Batch application**: ~1-2 seconds per directory

## Integration

### With Development Workflow

```bash
# Pre-commit spell check
cspellfix --all
git add .cspell-confirmed.toml

# CI/CD integration
cspellfix --source cspell --dry-run
```bash

### With AI Assistants

```bash
# Generate context
cspellfix --llm-prompt > spellcheck-context.md

# Apply AI suggestions
# [AI generates batch file]
cspellfix --batch-apply-cache
```bash

### With Project Management

```bash
# Multi-repo management
cspellfix --llm-auto  # Process all configured repos

# Project-specific words
echo 'approved = ["myproject"]' >> .cspell-confirmed.toml
```bash

## Technical Details

### Word Classification

- **Approved words**: Always accepted (`+word`)
- **Rejected words**: Always flagged (`-word`)
- **Replacements**: Auto-correct patterns (`=old:new`)
- **Ignored patterns**: Regex exclusions

### Source Priority

1. **trunk**: Fast, integrated (if available)
2. **cspell**: Native CLI, comprehensive
3. **scan**: Existing dictionaries only

### Batch File Format

```text
# Comments start with #
+word1          # Add to approved
-word2          # Add to rejected
=teh:the        # Auto-replace
!pattern        # Ignore regex pattern
```bash

### Configuration Hierarchy

1. **Global config**: `~/.config/zshand/cspell-global.toml`
2. **Project config**: `.cspell-confirmed.toml`
3. **Runtime options**: Command-line flags
4. **cSpell native**: `cspell.json` (fallback)

## Gotchas

### Global vs Project Configuration Conflicts

**Problem:** Words added to global config don't appear in project checks.

**Cause:** Configuration hierarchy prioritizes project over global by default.

**Solution:** Use `--global-first` flag or check config precedence:

```bash
# Check which config is active
cspellfix --dry-run --verbose
```bash

### LLM Batch Files Become Stale

**Problem:** AI-generated batch files contain outdated recommendations.

**Cause:** Project evolves faster than batch file updates.

**Solution:** Regenerate batch files regularly:

```bash
# Fresh batch for AI review
cspellfix --llm-prompt > fresh-prompt.md
```bash

### Source Detection Fails Silently

**Problem:** cspellfix runs but finds no misspelled words unexpectedly.

**Cause:** Source detection fails and falls back to scan mode.

**Solution:** Specify source explicitly and check for errors:

```bash
# Force specific source with verbose output
cspellfix --source trunk --verbose
```bash

### Auto-Replacements Break Code

**Problem:** Auto-replacements like `=teh:the` corrupt source code.

**Cause:** Over-aggressive replacement patterns.

**Solution:** Review replacements carefully and use selective approval:

```bash
# Review each replacement individually
cspellfix --interactive
```bash

### Multi-Directory Config Not Found

**Problem:** `--llm-auto` fails with "config not found" error.

**Cause:** Missing `cspellfix-dirs.toml` configuration file.

**Solution:** Create the configuration file:

```bash
# Create multi-directory config
mkdir -p ~/.config/zshand
cat > ~/.config/zshand/cspellfix-dirs.toml << 'EOF'
[dirs]
paths = ["~/.config/zshand", "~/logs/zshand", "~/.cache/zshand"]

[output]
batch_file = "~/.cache/zshand/cspellfix-batch.txt"
EOF
```bash

### Temporary Files Accumulate

**Problem:** Batch files and temp configs clutter directories.

**Cause:** cspellfix creates files but cleanup is manual.

**Solution:** Clean up regularly:

```bash
# Remove old batch files
find ~/.cache -name "cspellfix-batch*" -mtime +7 -delete
```bash

## See Also

- **[aicontext](aicontext.md)** - Generate AI context for projects
- **[scaffold](scaffold.md)** - Project scaffolding from AI
- **[TOML Configuration](../../README.md#configuration)** - Framework
  configuration format
- **[cSpell Documentation](https://cspell.org/)** - Upstream docs