skill-seekers-reference/CLI_OPTIONS_COMPLETE_LIST.md

Complete CLI Options & Flags - Everything Listed

Date: 2026-02-15 Purpose: Show EVERYTHING to understand the complexity

---

🎯 ANALYZE Command (20+ flags)

Required

• --directory DIR - Path to analyze

Preset System (NEW)

• --preset quick|standard|comprehensive - Bundled configuration
• --preset-list - Show available presets

Deprecated Flags (Still Work)

• --quick - Quick analysis [DEPRECATED → use --preset quick]
• --comprehensive - Full analysis [DEPRECATED → use --preset comprehensive]
• --depth surface|deep|full - Analysis depth [DEPRECATED → use --preset]

AI Enhancement (Multiple Ways)

• --enhance - Enable AI enhancement (default level 1)
• --enhance-level 0|1|2|3 - Specific enhancement level
  • 0 = None
  • 1 = SKILL.md only (default)
  • 2 = + Architecture + Config
  • 3 = Full (all features)

Feature Toggles (8 flags)

• --skip-api-reference - Disable API documentation
• --skip-dependency-graph - Disable dependency graph
• --skip-patterns - Disable pattern detection
• --skip-test-examples - Disable test extraction
• --skip-how-to-guides - Disable guide generation
• --skip-config-patterns - Disable config extraction
• --skip-docs - Disable docs extraction
• --no-comments - Skip comment extraction

Filtering

• --languages LANGS - Limit to specific languages
• --file-patterns PATTERNS - Limit to file patterns

Output

• --output DIR - Output directory
• --verbose - Verbose logging

Total: 20+ flags

---

🎯 SCRAPE Command (26+ flags)

Input (3 ways to specify)

• url (positional) - Documentation URL
• --url URL - Documentation URL (flag version)
• --config FILE - Load from config JSON

Basic Settings

• --name NAME - Skill name
• --description TEXT - Skill description

AI Enhancement (3 overlapping flags)

• --enhance - Claude API enhancement
• --enhance-local - Claude Code enhancement (no API key)
• --interactive-enhancement - Open terminal for enhancement
• --api-key KEY - API key for --enhance

Scraping Control

• --max-pages N - Maximum pages to scrape
• --skip-scrape - Use cached data
• --dry-run - Preview only
• --resume - Resume interrupted scrape
• --fresh - Start fresh (clear checkpoint)

Performance (4 flags)

• --rate-limit SECONDS - Delay between requests
• --no-rate-limit - Disable rate limiting
• --workers N - Parallel workers
• --async - Async mode

Interactive

• --interactive, -i - Interactive configuration

RAG Chunking (5 flags)

• --chunk-for-rag - Enable RAG chunking
• --chunk-size TOKENS - Chunk size (default: 512)
• --chunk-overlap TOKENS - Overlap size (default: 50)
• --no-preserve-code-blocks - Allow splitting code blocks
• --no-preserve-paragraphs - Ignore paragraph boundaries

Output Control

• --verbose, -v - Verbose output
• --quiet, -q - Quiet output

Total: 26+ flags

---

🎯 GITHUB Command (15+ flags)

Required

• --repo OWNER/REPO - GitHub repository

Basic Settings

• --output DIR - Output directory
• --api-key KEY - GitHub API token
• --profile NAME - GitHub token profile
• --non-interactive - CI/CD mode

Content Control

• --max-issues N - Maximum issues to fetch
• --include-changelog - Include CHANGELOG
• --include-releases - Include releases
• --no-issues - Skip issues

Enhancement

• --enhance - AI enhancement
• --enhance-local - Local enhancement

Other

• --languages LANGS - Filter languages
• --dry-run - Preview mode
• --verbose - Verbose logging

Total: 15+ flags

---

🎯 PACKAGE Command (12+ flags)

Required

• skill_directory - Skill directory to package

Target Platform (12 choices)

• --target PLATFORM - Target platform:
  • claude (default)
  • gemini
  • openai
  • markdown
  • langchain
  • llama-index
  • haystack
  • weaviate
  • chroma
  • faiss
  • qdrant

Options

• --upload - Auto-upload after packaging
• --no-open - Don't open output folder
• --skip-quality-check - Skip quality checks
• --streaming - Use streaming for large docs
• --chunk-size N - Chunk size for streaming

Total: 12+ flags + 12 platform choices

---

🎯 UPLOAD Command (10+ flags)

Required

• package_path - Package file to upload

Platform

• --target PLATFORM - Upload target
• --api-key KEY - Platform API key

Options

• --verify - Verify upload
• --retry N - Retry attempts
• --timeout SECONDS - Upload timeout

Total: 10+ flags

---

🎯 ENHANCE Command (7+ flags)

Required

• skill_directory - Skill to enhance

Mode Selection

• --mode api|local - Enhancement mode
• --enhance-level 0|1|2|3 - Enhancement level

Execution Control

• --background - Run in background
• --daemon - Detached daemon mode
• --timeout SECONDS - Timeout
• --force - Skip confirmations

Total: 7+ flags

---

📊 GRAND TOTAL ACROSS ALL COMMANDS

Command	Flags	Status
analyze	20+	⚠️ Confusing (presets + deprecated + granular)
scrape	26+	⚠️ Most complex
github	15+	⚠️ Multiple overlaps
package	12+ platforms	✅ Reasonable
upload	10+	✅ Reasonable
enhance	7+	⚠️ Mode confusion
Other commands	~30+	✅ Various

Total unique flags: 90+ Total with variations: 120+

---

🚨 OVERLAPPING CONCEPTS (Confusion Points)

1. AI Enhancement - 4 Different Ways

# In ANALYZE:
--enhance               # Turn on (uses level 1)
--enhance-level 0|1|2|3 # Specific level

# In SCRAPE:
--enhance               # Claude API
--enhance-local         # Claude Code
--interactive-enhancement  # Terminal mode

# In ENHANCE command:
--mode api|local        # Which system
--enhance-level 0|1|2|3 # How much

# Which one do I use? 🤔

2. Preset vs Manual - Competing Systems

# ANALYZE command has BOTH:

# Preset way:
--preset quick|standard|comprehensive

# Manual way (deprecated but still there):
--quick
--comprehensive
--depth surface|deep|full

# Granular way:
--skip-patterns
--skip-test-examples
--enhance-level 2

# Three ways to do the same thing! 🤔

3. RAG/Chunking - Spread Across Commands

# In SCRAPE:
--chunk-for-rag
--chunk-size 512
--chunk-overlap 50

# In PACKAGE:
--streaming
--chunk-size 4000  # Different default!

# In PACKAGE --format:
--format chroma|faiss|qdrant  # Vector DBs

# Where do RAG options belong? 🤔

4. Output Control - Inconsistent

# SCRAPE has:
--verbose
--quiet

# ANALYZE has:
--verbose  (no --quiet)

# GITHUB has:
--verbose

# PACKAGE has:
--no-open  (different pattern)

# Why different patterns? 🤔

5. Dry Run - Inconsistent

# SCRAPE has:
--dry-run

# GITHUB has:
--dry-run

# ANALYZE has:
(no --dry-run)  # Missing!

# Why not in analyze? 🤔

---

🎯 REAL USAGE SCENARIOS

Scenario 1: New User Wants to Analyze Codebase

What they see:

$ skill-seekers analyze --help

# 20+ options shown
# Multiple ways to do same thing
# No clear "start here" guidance

What they're thinking:

• 😵 "Do I use --preset or --depth?"
• 😵 "What's the difference between --enhance and --enhance-level?"
• 😵 "Should I use --quick or --preset quick?"
• 😵 "What do all these --skip-* flags mean?"

Result: Analysis paralysis, overwhelmed

---

Scenario 2: Experienced User Wants Fast Scrape

What they try:

# Try 1:
skill-seekers scrape https://docs.com --preset quick
# ERROR: unrecognized arguments: --preset

# Try 2:
skill-seekers scrape https://docs.com --quick
# ERROR: unrecognized arguments: --quick

# Try 3:
skill-seekers scrape https://docs.com --max-pages 50 --workers 5 --async
# WORKS! But hard to remember

# Try 4 (later discovers):
# Oh, scrape doesn't have presets yet? Only analyze does?

Result: Inconsistent experience across commands

---

Scenario 3: User Wants RAG Output

What they're confused about:

# Step 1: Scrape with RAG chunking?
skill-seekers scrape https://docs.com --chunk-for-rag

# Step 2: Package for vector DB?
skill-seekers package output/docs/ --format chroma

# Wait, chunk-for-rag in scrape sets chunk-size to 512
# But package --streaming uses chunk-size 4000
# Which one applies? Do they override each other?

Result: Unclear data flow

---

🎨 THE CORE PROBLEM

Too Many Layers:

Layer 1: Required args (--directory, url, etc.)
Layer 2: Preset system (--preset quick|standard|comprehensive)
Layer 3: Deprecated shortcuts (--quick, --comprehensive, --depth)
Layer 4: Granular controls (--skip-*, --enable-*)
Layer 5: AI controls (--enhance, --enhance-level, --enhance-local)
Layer 6: Performance (--workers, --async, --rate-limit)
Layer 7: RAG options (--chunk-for-rag, --chunk-size)
Layer 8: Output (--verbose, --quiet, --output)

8 conceptual layers! No wonder it's confusing.

---

✅ WHAT USERS ACTUALLY NEED

90% of users:

# Just want it to work
skill-seekers analyze --directory .
skill-seekers scrape https://docs.com
skill-seekers github --repo owner/repo

# Good defaults = Happy users

9% of users:

# Want to tweak ONE thing
skill-seekers analyze --directory . --enhance-level 3
skill-seekers scrape https://docs.com --max-pages 100

# Simple overrides = Happy power users

1% of users:

# Want full control
skill-seekers analyze --directory . \
  --depth full \
  --skip-patterns \
  --enhance-level 2 \
  --languages Python,JavaScript

# Granular flags = Happy experts

---

🎯 THE QUESTION

Do we need:

• ❌ Preset system? (adds layer)
• ❌ Deprecated flags? (adds confusion)
• ❌ Multiple AI flags? (inconsistent)
• ❌ Granular --skip-* for everything? (too many flags)

Or do we just need:

• ✅ Good defaults (works out of box)
• ✅ 3-5 key flags to adjust (depth, enhance-level, max-pages)
• ✅ Clear help text (show common usage)
• ✅ Consistent patterns (same flags across commands)

That's your question, right? 🎯