ColorScripts-Enhanced

2026.7.19.59

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 450++ beautiful ANSI colorscripts for terminal display. It selectively caches computationally expensive renderers while executing static artwork directly.
 
Policy-selected output is cached in 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. Static and unlisted scripts do not create cache entries.
 
### FEATURES
- 450++ 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 caches for all policy-selected renderers:
```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 for scripts listed in `CachePolicy.psd1`:
 
1. **Eligibility**: Static and unlisted scripts execute directly without cache I/O
2. **First Eligible Run**: A computational renderer executes and its output is cached
3. **Subsequent Eligible Runs**: Valid cached output displays immediately
4. **Auto-Refresh**: Cache regenerates when an eligible 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
Policy-selected computational renderers are slower on their first run while the cache is built. Static output scripts run directly. Pre-build eligible 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
 
Additional collections can be added via metadata. For example, Pokémon colorscripts can be grouped
under the `Pokemon` category in `ScriptMetadata.psd1` and then excluded with:
 
```powershell
Show-ColorScript -IncludePokemon
```
 
### 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
Evaluate scripts in the Geometric category and cache the policy-selected renderers:
```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 varies with each selected renderer
- Total cache size depends on the scripts selected in `CachePolicy.psd1`
- 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 policy-selected caches
New-ColorScriptCache -Name penrose-quasicrystal # Build a specific eligible cache
New-ColorScriptCache -Category Geometric # Build eligible caches in a 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:
 
**Eligible Cache Strategy** (Default)
```powershell
New-ColorScriptCache # Cache computational renderers only
# Pros: Avoids cache overhead for static art
# Cons: Policy changes require updating CachePolicy.psd1
```
 
**Filtered Eligible Cache Strategy** (Portable/CI)
```powershell
Get-ColorScriptList -Tag Recommended -AsObject |
    ForEach-Object { New-ColorScriptCache -Name $_.Name }
# Only policy-selected matches are cached
```
 
**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: 450++ built-in scripts across multiple categories and tags
 
**Q: How much disk space does caching use?**
A: It depends on the rendered output of the policy-selected scripts; static output scripts are not cached
 
**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
- 450++ 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 Unlicense License. See LICENSE file for details.