ColorScripts-Enhanced

2025.10.31.16

en-US/about_ColorScripts-Enhanced.help.txt

# ColorScripts-Enhanced Module Help
 
## about_ColorScripts-Enhanced
 
### SHORT DESCRIPTION
Enhanced PowerShell ColorScripts with high-performance caching system for displaying beautiful ANSI art in your terminal.
 
### LONG DESCRIPTION
ColorScripts-Enhanced is a PowerShell module that provides a collection of 295+ beautiful ANSI colorscripts for terminal display. It features an intelligent caching system that provides 6-19x performance improvements over traditional script execution.
 
The module automatically caches script output to a centralized location in your AppData folder, enabling instant display on subsequent runs. Cache files are automatically validated and regenerated when source scripts are modified.
 
### FEATURES
- 295+ beautiful pre-made colorscripts
- High-performance caching system (6-19x faster)
- Centralized cache location (works from any directory)
- Automatic cache invalidation on script changes
- UTF-8 encoding support for perfect rendering
- Random colorscript selection
- Easy script discovery and listing
- Profile helper for one-line startup integration
- Persistent configuration helpers for cache and startup behaviour
- Metadata export and scaffolding workflows for custom scripts
 
### INSTALLATION
 
#### From PowerShell Gallery (Recommended)
```powershell
Install-Module -Name ColorScripts-Enhanced -Scope CurrentUser
```
 
Add the module to your profile automatically:
 
```powershell
Add-ColorScriptProfile # Import + Show-ColorScript
Add-ColorScriptProfile -SkipStartupScript
```
 
#### Manual Installation
1. Download the module from GitHub
2. Extract to a PowerShell module path:
   - User: `$HOME\Documents\PowerShell\Modules\ColorScripts-Enhanced`
   - System: `C:\Program Files\PowerShell\Modules\ColorScripts-Enhanced`
3. Import the module:
   ```powershell
   Import-Module ColorScripts-Enhanced
   ```
 
### QUICK START
 
Display a random colorscript:
```powershell
Show-ColorScript
# or use the alias
scs
```
 
Display a specific colorscript:
```powershell
Show-ColorScript -Name hearts
scs mandelbrot-zoom
```
 
List all available colorscripts:
```powershell
Show-ColorScript -List
Get-ColorScriptList
```
 
Pre-build cache for all scripts:
```powershell
New-ColorScriptCache
```
 
### COMMANDS
 
The module exports the following commands:
 
- `Show-ColorScript` - Display colorscripts (alias: scs)
- `Get-ColorScriptList` - List available colorscripts
- `New-ColorScriptCache` - Pre-generate cache files
- `Clear-ColorScriptCache` - Remove cache files
- `Add-ColorScriptProfile` - Append module startup snippet to a PowerShell profile
- `Get-ColorScriptConfiguration` - Inspect cache and startup defaults
- `Set-ColorScriptConfiguration` - Persist custom configuration values
- `Reset-ColorScriptConfiguration` - Restore configuration defaults
- `Export-ColorScriptMetadata` - Export script metadata for automation
- `New-ColorScript` - Scaffold a new colorscript and metadata snippet
 
Use `Get-Help <CommandName> -Full` for detailed help on each command.
 
### CACHE SYSTEM
 
The caching system works automatically:
 
1. **First Run**: Script executes normally and output is cached
2. **Subsequent Runs**: Cached output displays instantly (6-19x faster)
3. **Auto-Refresh**: Cache regenerates when script is modified
 
**Cache Location**: `$env:APPDATA\ColorScripts-Enhanced\cache`
 
**Cache Benefits**:
- Instant display of complex colorscripts
- Reduced CPU usage
- Consistent performance
- Works from any directory
 
### CONFIGURATION
 
#### Add to PowerShell Profile
Display a random colorscript on every terminal launch:
 
```powershell
Add-ColorScriptProfile # Import + Show-ColorScript
Add-ColorScriptProfile -SkipStartupScript
```
 
#### Customize Cache Location
The cache location is automatically set based on your platform:
 
Windows:
```powershell
$env:APPDATA\ColorScripts-Enhanced\cache
```
 
macOS:
```powershell
~/Library/Application Support/ColorScripts-Enhanced/cache
```
 
Linux:
```powershell
~/.cache/ColorScripts-Enhanced
```
 
### NERD FONT GLYPHS
 
Some scripts display Nerd Font icons (developer glyphs, powerline separators, checkmarks). Install a patched font so those characters render correctly:
 
1. Download a font from https://www.nerdfonts.com/ (popular choices: Cascadia Code, JetBrainsMono, FiraCode).
2. Windows: extract the `.zip`, select the `.ttf` files, right-click → **Install for all users**.
   macOS: `brew install --cask font-caskaydia-cove-nerd-font` or add via Font Book.
   Linux: copy `.ttf` files to `~/.local/share/fonts` (or `/usr/local/share/fonts`) and run `fc-cache -fv`.
3. Set your terminal profile to use the installed Nerd Font.
4. Verify glyphs with:
 
```powershell
Show-ColorScript -Name nerd-font-test
```
 
### EXAMPLES
 
#### Example 1: Random Colorscript on Startup
```powershell
# In your $PROFILE file:
Import-Module ColorScripts-Enhanced
Show-ColorScript
```
 
#### Example 2: Daily Different Colorscript
```powershell
# Use the date as seed for consistent daily script
$seed = (Get-Date).DayOfYear
Get-Random -SetSeed $seed
Show-ColorScript
```
 
#### Example 3: Build Cache for Favorite Scripts
```powershell
New-ColorScriptCache -Name hearts,mandelbrot-zoom,galaxy-spiral
```
 
#### Example 4: Force Cache Rebuild
```powershell
New-ColorScriptCache -Force
```
 
### TROUBLESHOOTING
 
#### Scripts not displaying correctly
Ensure your terminal supports UTF-8 and ANSI escape codes:
```powershell
[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
```
 
#### Cache not working
Clear and rebuild cache:
```powershell
Clear-ColorScriptCache -All
New-ColorScriptCache
```
 
#### Performance issues
The first run of each script will be slower as it builds cache. Pre-build all caches:
```powershell
New-ColorScriptCache
```
 
### PERFORMANCE
 
Typical performance improvements with caching:
 
| Script Type | Without Cache | With Cache | Speedup |
|------------|---------------|------------|---------|
| Simple | ~50ms | ~8ms | 6x |
| Medium | ~150ms | ~12ms | 12x |
| Complex | ~300ms | ~16ms | 19x |
 
### SCRIPT CATEGORIES
 
The module includes scripts in various categories:
 
- **Geometric**: mandelbrot-zoom, apollonian-circles, sierpinski-carpet
- **Nature**: galaxy-spiral, aurora-bands, crystal-drift
- **Artistic**: kaleidoscope, rainbow-waves, prismatic-rain
- **Gaming**: doom, pacman, space-invaders
- **System**: colortest, nerd-font-test, terminal-benchmark
- **Logos**: arch, debian, ubuntu, windows
 
### SEE ALSO
 
- GitHub Repository: https://github.com/Nick2bad4u/ps-color-scripts-enhanced
- Original inspiration: shell-color-scripts
- PowerShell Documentation: https://docs.microsoft.com/powershell/
 
### KEYWORDS
- ANSI
- Terminal
- Art
- ASCII
- Color
- Scripts
- Cache
- Performance
 
### ADVANCED USAGE
 
#### Building Cache for Specific Categories
Cache all scripts in the Geometric category for optimal performance:
```powershell
Get-ColorScriptList -Category Geometric -AsObject |
    ForEach-Object { New-ColorScriptCache -Name $_.Name }
```
 
#### Performance Measurement
Measure the performance improvement from caching:
```powershell
# Uncached performance (cold start)
Remove-Module ColorScripts-Enhanced -ErrorAction SilentlyContinue
$uncached = Measure-Command {
    Import-Module ColorScripts-Enhanced
    Show-ColorScript -Name "mandelbrot-zoom" -NoCache
}
 
# Cached performance (warm start)
$cached = Measure-Command {
    Show-ColorScript -Name "mandelbrot-zoom"
}
 
Write-Host "Uncached: $($uncached.TotalMilliseconds)ms"
Write-Host "Cached: $($cached.TotalMilliseconds)ms"
Write-Host "Speedup: $([math]::Round($uncached.TotalMilliseconds / $cached.TotalMilliseconds, 1))x"
```
 
#### Automation: Display Different Script Daily
Set up your profile to show a different script each day:
```powershell
# In your $PROFILE file:
$seed = (Get-Date).DayOfYear
[System.Random]::new($seed).Next()
Get-Random -SetSeed $seed
Show-ColorScript
```
 
#### Pipeline Operations with Metadata
Export colorscript metadata for use in other tools:
```powershell
# Export to JSON for web dashboard
Export-ColorScriptMetadata -Path ./dist/colorscripts.json -IncludeFileInfo
 
# Count scripts by category
Get-ColorScriptList -AsObject |
    Group-Object Category |
    Select-Object Name, Count |
    Sort-Object Count -Descending
 
# Find scripts with specific keywords
$scripts = Get-ColorScriptList -AsObject
$scripts |
    Where-Object { $_.Description -match 'fractal|mandelbrot' } |
    Select-Object Name, Category, Description
```
 
#### Cache Management for CI/CD Environments
Configure and manage cache for automated deployments:
```powershell
# Set temporary cache location for CI/CD
Set-ColorScriptConfiguration -CachePath $env:TEMP\colorscripts-cache
 
# Pre-build cache for deployment
$productionScripts = @('bars', 'arch', 'ubuntu', 'windows', 'rainbow-waves')
New-ColorScriptCache -Name $productionScripts -Force
 
# Verify cache health
$cacheDir = (Get-ColorScriptConfiguration).Cache.Path
Get-ChildItem $cacheDir -Filter "*.cache" | Measure-Object -Sum Length
```
 
#### Filtering and Display Workflows
Advanced filtering for customized displays:
```powershell
# Display all recommended scripts with details
Get-ColorScriptList -Tag Recommended -Detailed
 
# Show geometric scripts with caching disabled for testing
Get-ColorScriptList -Category Geometric -Name "aurora-*" -AsObject |
    ForEach-Object { Show-ColorScript -Name $_.Name -NoCache }
 
# Export metadata filtered by category
Export-ColorScriptMetadata -IncludeFileInfo |
    Where-Object { $_.Category -eq 'Animated' } |
    ConvertTo-Json |
    Out-File "./animated-scripts.json"
```
 
### ENVIRONMENT VARIABLES
 
The module respects the following environment variables:
 
- **COLORSCRIPTS_CACHE**: Override the default cache location
- **PSModulePath**: Affects where the module is discovered
 
### PERFORMANCE TUNING
 
#### Typical Performance Metrics
| Script Complexity | Without Cache | With Cache | Improvement |
|------------------|---------------|------------|-------------|
| Simple (50-100ms) | ~50ms | ~8ms | 6x faster |
| Medium (100-200ms) | ~150ms | ~12ms | 12x faster |
| Complex (200-300ms) | ~300ms | ~16ms | 19x faster |
 
#### Cache Size Information
- Average cache file size: 2-50KB per script
- Total cache size for all scripts: ~2-5MB
- Cache location: Uses OS-appropriate paths for minimal footprint
 
### TROUBLESHOOTING ADVANCED ISSUES
 
#### Module Not Found Error
```powershell
# Check if module is in PSModulePath
Get-Module ColorScripts-Enhanced -ListAvailable
 
# List available module paths
$env:PSModulePath -split ';'
 
# Import from explicit path if necessary
Import-Module "C:\Path\To\ColorScripts-Enhanced\ColorScripts-Enhanced.psd1"
```
 
#### Cache Corruption
Clear and rebuild completely:
```powershell
# Remove module from session
Remove-Module ColorScripts-Enhanced -Force
 
# Clear all cache files
Clear-ColorScriptCache -All -Confirm:$false
 
# Reimport and rebuild cache
Import-Module ColorScripts-Enhanced
New-ColorScriptCache -Force
```
 
#### Performance Degradation
If performance worsens over time:
```powershell
# Check cache directory size
$cacheDir = (Get-ColorScriptConfiguration).Cache.Path
$size = (Get-ChildItem $cacheDir -Filter "*.cache" |
    Measure-Object -Sum Length).Sum
Write-Host "Cache size: $([math]::Round($size / 1MB, 2)) MB"
 
# Clear old cache and rebuild
Clear-ColorScriptCache -All
New-ColorScriptCache
```
 
### PLATFORM-SPECIFIC NOTES
 
#### Windows PowerShell 5.1
- Limited to Windows only
- Use `powershell.exe` to run scripts
- Some advanced features may be unavailable
- Recommended to upgrade to PowerShell 7+
 
#### PowerShell 7+ (Cross-Platform)
- Full support on Windows, macOS, and Linux
- Use `pwsh` command
- All features fully functional
- Recommended for new deployments
 
### DETAILED COMMAND REFERENCE
 
#### Core Commands Overview
The module provides 10 main commands for managing and displaying colorscripts:
 
**Display Commands:**
- `Show-ColorScript` - Display colorscripts with multiple modes (random, named, list, all)
- `Get-ColorScriptList` - List available colorscripts with detailed metadata
 
**Cache Management:**
- `New-ColorScriptCache` - Build cache files for performance
- `Clear-ColorScriptCache` - Remove cache files with filtering options
- `Build-ColorScriptCache` - Alias for New-ColorScriptCache
 
**Configuration:**
- `Get-ColorScriptConfiguration` - Retrieve current configuration settings
- `Set-ColorScriptConfiguration` - Persist configuration changes
- `Reset-ColorScriptConfiguration` - Restore factory defaults
 
**Profile Integration:**
- `Add-ColorScriptProfile` - Integrate module into PowerShell profile
 
**Development:**
- `New-ColorScript` - Scaffold new colorscript template
- `Export-ColorScriptMetadata` - Export metadata for automation
 
#### Command Usage Patterns
 
**Pattern 1: Quick Display**
```powershell
Show-ColorScript # Random colorscript
scs # Using module alias
Show-ColorScript -Name aurora # Specific script
```
 
**Pattern 2: Discovery and Listing**
```powershell
Get-ColorScriptList # All scripts
Get-ColorScriptList -Detailed # With tags and descriptions
Get-ColorScriptList -Category Nature # Filter by category
Get-ColorScriptList -Tag Animated # Filter by tag
```
 
**Pattern 3: Performance Optimization**
```powershell
New-ColorScriptCache # Build all caches
New-ColorScriptCache -Name bars # Build specific cache
New-ColorScriptCache -Category Geometric # Build category
```
 
**Pattern 4: Cache Maintenance**
```powershell
Clear-ColorScriptCache -All # Remove all caches
Clear-ColorScriptCache -Name "test-*" # Clear pattern
Clear-ColorScriptCache -Category Demo # Clear by category
```
 
### DETAILED WORKFLOW EXAMPLES
 
#### Workflow 1: Initial Setup and Configuration
```powershell
# Step 1: Install the module
Install-Module -Name ColorScripts-Enhanced -Scope CurrentUser
 
# Step 2: Add to profile for automatic startup
Add-ColorScriptProfile
 
# Step 3: Pre-build cache for optimal performance
New-ColorScriptCache
 
# Step 4: Verify setup
Get-ColorScriptConfiguration
```
 
#### Workflow 2: Daily Use with Rotation
```powershell
# In $PROFILE file, add:
Import-Module ColorScripts-Enhanced
 
# Display different script each day based on date
$seed = (Get-Date).DayOfYear
Get-Random -SetSeed $seed
Show-ColorScript -Random
 
# Alternative: Show specific category
Show-ColorScript -Category Geometric -Random
```
 
#### Workflow 3: Automation Integration
```powershell
# Export metadata for external tools
$metadata = Export-ColorScriptMetadata -IncludeFileInfo -IncludeCacheInfo
$metadata | ConvertTo-Json | Out-File "./colorscripts.json"
 
# Use in automation: cycle through scripts
$scripts = Get-ColorScriptList -Tag Recommended -AsObject
$scripts | ForEach-Object { Show-ColorScript -Name $_.Name; Start-Sleep -Seconds 2 }
```
 
#### Workflow 4: Performance Monitoring
```powershell
# Measure cache effectiveness
$uncached = Measure-Command { Show-ColorScript -Name mandelbrot-zoom -NoCache }
$cached = Measure-Command { Show-ColorScript -Name mandelbrot-zoom }
 
Write-Host "Uncached: $($uncached.TotalMilliseconds)ms"
Write-Host "Cached: $($cached.TotalMilliseconds)ms"
Write-Host "Improvement: $([math]::Round($uncached.TotalMilliseconds / $cached.TotalMilliseconds, 1))x"
```
 
#### Workflow 5: Customization and Development
```powershell
# Create custom colorscript
New-ColorScript -Name "my-custom-art" -Category "Custom" -Tag "MyTag" -GenerateMetadataSnippet
 
# Edit the script
code "$env:USERPROFILE\Documents\PowerShell\Modules\ColorScripts-Enhanced\Scripts\my-custom-art.ps1"
 
# Add metadata (use guidance from generation)
# Edit ScriptMetadata.psd1
 
# Cache and test
New-ColorScriptCache -Name "my-custom-art" -Force
Show-ColorScript -Name "my-custom-art"
```
 
### INTEGRATION SCENARIOS
 
#### Scenario 1: Terminal Welcome Screen
```powershell
# In profile:
$hour = (Get-Date).Hour
if ($hour -ge 6 -and $hour -lt 12) {
    Show-ColorScript -Tag "bright,morning" -Random
} elseif ($hour -ge 12 -and $hour -lt 18) {
    Show-ColorScript -Category Geometric -Random
} else {
    Show-ColorScript -Tag "night,dark" -Random
}
```
 
#### Scenario 2: CI/CD Pipeline
```powershell
# Build phase decoration
Show-ColorScript -Name "bars" -NoCache # Quick display without cache
New-ColorScriptCache -Category "Build" -Force # Prepare for next run
 
# In CI/CD context:
$env:CI = $true
if ($env:CI) {
    Show-ColorScript -NoCache # Avoid cache in ephemeral environments
}
```
 
#### Scenario 3: Administrative Dashboards
```powershell
# Display system-themed colorscripts
$os = if ($PSVersionTable.PSVersion.Major -ge 7) { "pwsh" } else { "powershell" }
Show-ColorScript -Name $os -PassThru | Out-Null
 
# Show status information
Get-ColorScriptList -Tag "system" -AsObject |
    ForEach-Object { Write-Host "Available: $($_.Name)" }
```
 
#### Scenario 4: Educational Presentations
```powershell
# Interactive colorscript showcase
Show-ColorScript -All -WaitForInput
# Users can press space to advance, q to quit
 
# Or with specific category
Show-ColorScript -All -Category Abstract -WaitForInput
```
 
#### Scenario 5: Multi-User Environment
```powershell
# Per-user configuration
Set-ColorScriptConfiguration -CachePath "\\shared\cache\$env:USERNAME"
Set-ColorScriptConfiguration -DefaultScript "team-logo"
 
# Shared scripts with user customization
Get-ColorScriptList -AsObject |
    Where-Object { $_.Tags -contains "shared" } |
    ForEach-Object { Show-ColorScript -Name $_.Name }
```
 
### ADVANCED TOPICS
 
#### Topic 1: Cache Strategy Selection
Different caching strategies for different scenarios:
 
**Full Cache Strategy** (Optimal for Workstations)
```powershell
New-ColorScriptCache # Cache all 295+ scripts
# Pros: Maximum performance, instant display
# Cons: Uses 2-5MB disk space
```
 
**Selective Cache Strategy** (Optimal for Portable/CI)
```powershell
Get-ColorScriptList -Tag Recommended -AsObject |
    ForEach-Object { New-ColorScriptCache -Name $_.Name }
# Pros: Balanced performance and storage
# Cons: Requires more setup
```
 
**No Cache Strategy** (Optimal for Development)
```powershell
Show-ColorScript -NoCache
# Pros: See script changes immediately
# Cons: Slower display, more resource usage
```
 
#### Topic 2: Metadata Organization
Understanding and organizing colorscripts by metadata:
 
**Categories** - Broad organizational groupings:
- Geometric: Fractals, mathematical patterns
- Nature: Landscapes, organic themes
- Artistic: Creative, abstract designs
- Gaming: Game-related themes
- System: OS/technology themed
 
**Tags** - Specific descriptors:
- Recommended: Curated for general use
- Animated: Moving/changing patterns
- Colorful: Multi-color palettes
- Minimal: Simple, clean designs
- Retro: Classic 80s/90s aesthetics
 
#### Topic 3: Performance Optimization Tips
```powershell
# Tip 1: Pre-load frequently used scripts
New-ColorScriptCache -Name bars,arch,mandelbrot-zoom,aurora-waves
 
# Tip 2: Monitor cache staleness
$old = Get-ChildItem "$env:APPDATA\ColorScripts-Enhanced\cache" -Filter "*.cache" |
    Where-Object { $_.LastWriteTime -lt (Get-Date).AddMonths(-1) }
 
# Tip 3: Use category filtering for faster selection
Show-ColorScript -Category Geometric # Faster than full set
 
# Tip 4: Enable verbose output for debugging
Show-ColorScript -Name aurora -Verbose
```
 
#### Topic 4: Cross-Platform Considerations
```powershell
# Windows Terminal specific
if ($env:WT_SESSION) {
    Show-ColorScript # Full color support
}
 
# VS Code integrated terminal
if ($env:TERM_PROGRAM -eq "vscode") {
    Show-ColorScript -Name nerd-font-test # Font support
}
 
# SSH session
if ($env:SSH_CONNECTION) {
    Show-ColorScript -NoCache # Avoid slow network cache I/O
}
 
# Linux/macOS terminal
if ($PSVersionTable.PSVersion.Major -ge 7) {
    Show-ColorScript -Category Nature # Use Unix-friendly scripts
}
```
 
#### Topic 5: Scripting and Automation
```powershell
# Create reusable function for daily greeting
function Show-DailyColorScript {
    $seed = (Get-Date).DayOfYear
    Get-Random -SetSeed $seed
    Show-ColorScript -Random -Category @("Geometric", "Nature") -Random
}
 
# Use in profile
Show-DailyColorScript
 
# Create script rotation function
function Invoke-ColorScriptSlideshow {
    param(
        [int]$Interval = 3,
        [string[]]$Category,
        [int]$Count
    )
 
    $scripts = if ($Category) {
        Get-ColorScriptList -Category $Category -AsObject
    } else {
        Get-ColorScriptList -AsObject
    }
 
    $scripts | Select-Object -First $Count | ForEach-Object {
        Show-ColorScript -Name $_.Name
        Start-Sleep -Seconds $Interval
    }
}
 
# Usage
Invoke-ColorScriptSlideshow -Interval 2 -Category Geometric -Count 5
```
 
### TROUBLESHOOTING GUIDE
 
#### Issue 1: Scripts Not Displaying Correctly
**Symptoms**: Garbled characters or missing colors
**Solutions**:
```powershell
# Set UTF-8 encoding
[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
 
# Check terminal supports UTF-8
Write-Host "Test: ✓ ✗ ◆ ○" -ForegroundColor Green
 
# Use nerd font test
Show-ColorScript -Name nerd-font-test
 
# If still broken, disable cache
Show-ColorScript -Name yourscript -NoCache
```
 
#### Issue 2: Module Import Failures
**Symptoms**: "Module not found" or import errors
**Solutions**:
```powershell
# Check if module exists
Get-Module -ListAvailable | Where-Object Name -like "*Color*"
 
# Check PSModulePath
$env:PSModulePath -split [System.IO.Path]::PathSeparator
 
# Reinstall module
Remove-Module ColorScripts-Enhanced
Uninstall-Module ColorScripts-Enhanced
Install-Module -Name ColorScripts-Enhanced -Force
```
 
#### Issue 3: Cache Not Being Used
**Symptoms**: Scripts run slowly every time
**Solutions**:
```powershell
# Verify cache exists
$cacheDir = (Get-ColorScriptConfiguration).Cache.Path
Get-ChildItem $cacheDir -Filter "*.cache" | Measure-Object
 
# Rebuild cache
Remove-Item "$cacheDir\*" -Confirm:$false
New-ColorScriptCache -Force
 
# Check for cache path issues
Get-ColorScriptConfiguration | Select-Object -ExpandProperty Cache
```
 
#### Issue 4: Profile Not Running
**Symptoms**: Colorscript doesn't show on PowerShell startup
**Solutions**:
```powershell
# Verify profile exists
Test-Path $PROFILE
 
# Check profile content
Get-Content $PROFILE | Select-String "ColorScripts"
 
# Repair profile
Add-ColorScriptProfile -Force
 
# Test profile manually
. $PROFILE
```
 
### FAQ
 
**Q: How many colorscripts are available?**
A: 295+ built-in scripts across multiple categories and tags
 
**Q: How much disk space does caching use?**
A: Approximately 2-5MB total for all scripts, about 2-50KB per script
 
**Q: Can I use colorscripts in scripts/automation?**
A: Yes, use `-ReturnText` to capture output or `-PassThru` for metadata
 
**Q: How do I create custom colorscripts?**
A: Use `New-ColorScript` to scaffold a template, then add your ANSI art
 
**Q: What if I don't want colors on startup?**
A: Use `Add-ColorScriptProfile -SkipStartupScript` to import without auto-display
 
**Q: Can I use this on macOS/Linux?**
A: Yes, with PowerShell 7+ which runs cross-platform
 
**Q: How do I share colorscripts with colleagues?**
A: Export metadata with `Export-ColorScriptMetadata` or share script files
 
**Q: Is caching always enabled?**
A: No, use `-NoCache` to disable caching for development/testing
 
### BEST PRACTICES
 
1. **Install from PowerShell Gallery**: Use `Install-Module` for automatic updates
2. **Add to Profile**: Use `Add-ColorScriptProfile` for automatic startup integration
3. **Pre-build Cache**: Run `New-ColorScriptCache` after installation for optimal performance
4. **Use Meaningful Naming**: When creating custom scripts, use descriptive names
5. **Keep Metadata Updated**: Update ScriptMetadata.psd1 when adding scripts
6. **Test in Different Terminals**: Verify scripts display correctly across your environments
7. **Monitor Cache Size**: Periodically check cache directory size and clean if needed
8. **Use Categories/Tags**: Leverage filtering for faster script discovery
9. **Document Custom Scripts**: Add descriptions and tags to custom colorscripts
10. **Backup Configuration**: Export configuration before major changes
 
### VERSION HISTORY
 
#### Version 2025.10.09
- Enhanced caching system with OS-wide cache
- 6-19x performance improvement
- Centralized cache location in AppData
- 295+ colorscripts included
- Full comment-based help documentation
- Module manifest improvements
- Advanced configuration management
- Metadata export capabilities
- Profile integration helpers
 
### COPYRIGHT
 
Copyright (c) 2025. All rights reserved.
 
### LICENSE
 
Licensed under MIT License. See LICENSE file for details.