# CLI User Experience Specification
## Overview
The `seams` CLI is designed for narrative analysis pipeline builders who need a high-performance, hassle-free tool for sentence extraction from Project Gutenberg texts. This specification defines the user experience requirements for installation, usage, error handling, and integration with automated workflows.
## Target Audience
**Primary Users**: Developers and researchers building narrative analysis pipelines who need:
- Fast sentence extraction with span metadata
- Reliable batch processing of large text corpora
- Integration with existing CI/CD and data processing workflows
- Minimal setup and configuration overhead
## Installation Experience
### Requirement: Zero-friction Installation
```bash
cargo install seams
```
**Success Criteria:**
- Single command installation from crates.io
- No additional dependencies or setup required
- Cross-platform compatibility (macOS, Windows, Linux)
- Clear error messages if installation fails
### Verification Commands
```bash
# Verify installation
seams --version
# Should output: seams 0.1.0
# Verify help access
seams --help
# Should show comprehensive usage guide
```
## Command Line Interface
### Help System
**Comprehensive `--help` Output:**
```
seams 0.1.0
High-throughput sentence extractor for Project Gutenberg texts
USAGE:
seams [OPTIONS] <ROOT_DIR>
ARGS:
<ROOT_DIR> Directory containing Project Gutenberg *-0.txt files
OPTIONS:
--overwrite_all Overwrite even complete aux files
--fail_fast Abort on first error (default: continue with logging)
--no_progress Suppress progress bars (useful for CI)
--stats_out <PATH> Stats output file [default: run_stats.json]
-h, --help Print help information
-V, --version Print version information
EXAMPLES:
# Process Project Gutenberg mirror
seams /path/to/gutenberg
# Process with progress suppressed for CI
seams --no_progress /path/to/gutenberg
# Overwrite existing results
seams --overwrite_all /path/to/gutenberg
# Process with fail-fast enabled
seams --fail_fast /path/to/gutenberg
OUTPUT:
Creates *_seams.txt files alongside source files with format:
<index> <sentence> (<start_line>,<start_col>,<end_line>,<end_col>)
```
### Progress Feedback
**Interactive Mode (default):**
- Multi-line progress bars showing:
- Files processed/total
- Current throughput (MB/s, chars/s)
- ETA
- Current file being processed
**CI/Pipeline Mode (`--no_progress`):**
- Structured log output only
- No interactive progress bars
- Suitable for automated environments
## Error Handling
### Actionable Error Messages
**File Access Errors:**
```
Error: Cannot access root directory '/nonexistent/path'
→ Check that the path exists and you have read permissions
→ Use 'ls -la /nonexistent' to verify directory status
```
**Invalid UTF-8 Files:**
```
Error: Invalid UTF-8 in file '/path/to/file-0.txt'
→ This file contains non-UTF-8 content and will be skipped
→ Use '--fail_fast' to abort processing on first error
→ Check file encoding with 'file /path/to/file-0.txt'
```
**Permission Errors:**
```
Error: Cannot write auxiliary file '/path/to/file_seams.txt'
→ Check write permissions in the target directory
→ Use 'ls -la /path/to' to verify directory permissions
```
**Memory/Performance Warnings:**
```
Warning: Large file detected (500MB+), processing with optimized memory-mapped I/O
→ High-performance processing mode automatically enabled
→ Current file: /path/to/large-file-0.txt
```
### Error Recovery
**Default Behavior (continue processing):**
- Log errors with context
- Mark failed files in statistics
- Continue processing remaining files
- Exit with non-zero code if any files failed
**Fail-fast Mode (`--fail_fast`):**
- Abort immediately on first error
- Provide detailed error context
- Exit with descriptive error code
## Shell Integration
### Shell Completion
**Supported Shells:**
- bash
- zsh
- fish
**Installation:**
```bash
# Generate completion script
seams --generate-completion bash > ~/.bash_completion.d/seams
seams --generate-completion zsh > ~/.zsh/completions/_seams
seams --generate-completion fish > ~/.config/fish/completions/seams.fish
```
**Completion Features:**
- Path completion for `<ROOT_DIR>`
- Flag completion with descriptions
- Context-aware suggestions
## Integration with Workflows
### CI/CD Pipeline Integration
**Recommended Usage:**
```bash
# In CI scripts
seams --no_progress --fail_fast /data/gutenberg
if [ $? -eq 0 ]; then
echo "Sentence extraction completed successfully"
else
echo "Sentence extraction failed"
exit 1
fi
```
**Output Handling:**
- Structured JSON logs for parsing
- Predictable exit codes
- Statistics in machine-readable format
### Data Pipeline Integration
**Batch Processing:**
```bash
# Process multiple corpora
for corpus in /data/gutenberg-*; do
seams --stats_out "stats_$(basename $corpus).json" "$corpus"
done
```
**Performance Monitoring:**
```bash
# Extract performance metrics
## Performance Characteristics
### Throughput Expectations
- **Target**: >30M characters/second on modern hardware
- **Scalability**: Utilizes multiple CPU cores automatically
- **Memory**: Bounded memory usage regardless of file size
### Cold Start Performance
- **Startup Time**: <100ms for DFA initialization
- **First File**: Processing begins immediately after startup
- **Comparison**: Superior to generic sentence detection tools
## Validation and Testing
### User Acceptance Testing
1. **Installation Test**: Fresh system, `cargo install seams` works
2. **Help Test**: `seams --help` provides comprehensive guidance
3. **Error Test**: Invalid inputs produce actionable error messages
4. **Workflow Test**: Integration with common CI/CD patterns works
5. **Performance Test**: Meets throughput requirements on reference hardware
### Success Metrics
- Time-to-first-success < 5 minutes from installation
- Error resolution rate: Users can fix common issues from error messages
- Integration success: Works in automated workflows without manual intervention