firefrost-gaming/skill-seekers-reference
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
1ea5a5c7c28afa374fad86dfeb9fc5d4adcbfd08
skill-seekers-reference/CLI_OPTIONS_COMPLETE_LIST.md
yusyus ba1670a220 feat: Unified create command + consolidated enhancement flags 
This commit includes two major improvements:

## 1. Unified Create Command (v3.0.0 feature)
- Auto-detects source type (web, GitHub, local, PDF, config)
- Three-tier argument organization (universal, source-specific, advanced)
- Routes to existing scrapers (100% backward compatible)
- Progressive disclosure: 15 universal flags in default help

**New files:**
- src/skill_seekers/cli/source_detector.py - Auto-detection logic
- src/skill_seekers/cli/arguments/create.py - Argument definitions
- src/skill_seekers/cli/create_command.py - Main orchestrator
- src/skill_seekers/cli/parsers/create_parser.py - Parser integration

**Tests:**
- tests/test_source_detector.py (35 tests)
- tests/test_create_arguments.py (30 tests)
- tests/test_create_integration_basic.py (10 tests)

## 2. Enhanced Flag Consolidation (Phase 1)
- Consolidated 3 flags (--enhance, --enhance-local, --enhance-level) → 1 flag
- --enhance-level 0-3 with auto-detection of API vs LOCAL mode
- Default: --enhance-level 2 (balanced enhancement)

**Modified files:**
- arguments/{common,create,scrape,github,analyze}.py - Added enhance_level
- {doc_scraper,github_scraper,config_extractor,main}.py - Updated logic
- create_command.py - Uses consolidated flag

**Auto-detection:**
- If ANTHROPIC_API_KEY set → API mode
- Else → LOCAL mode (Claude Code)

## 3. PresetManager Bug Fix
- Fixed module naming conflict (presets.py vs presets/ directory)
- Moved presets.py → presets/manager.py
- Updated __init__.py exports

**Test Results:**
- All 160+ tests passing
- Zero regressions
- 100% backward compatible

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
2026-02-15 14:29:19 +03:00

446 lines
10 KiB
Markdown
Raw Blame History

# 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**
```bash
# 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**
```bash
# 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**
```bash
# 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**
```bash
# 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**
```bash
# 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:**
```bash
$ 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:**
```bash
# 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:**
```bash
# 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:**
```bash
# 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:**
```bash
# 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:**
```bash
# 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?** 🎯
Reference in New Issue View Git Blame Copy Permalink