ColorScripts-Enhanced PowerShell Module

Credits: This project owes its existence to the foundational work of two developers. The beautiful ANSI art scripts were originally created and/or sourced by Derek Taylor (DistroTube) in his project shell-color-scripts. The collection was then ported to PowerShell by Scott McKendry as ps-color-scripts. ColorScripts-Enhanced builds upon their efforts by introducing a high-performance caching system, PowerShell Cross-Platform support on Linux and Mac, an expanded command set, and a formal module structure.

A high-performance PowerShell module for displaying beautiful ANSI colorscripts in your terminal with intelligent caching for 6-19x faster load times.

Table of Contents

• Features
• Demo
• Quick Start
• PowerShell Support
• Install a Nerd Font
• Installation
• Usage
• Performance
• Available Colorscripts
• Commands
• Documentation
• Contributing
• License
• Support

Features

✨ 498+ Beautiful Colorscripts - Extensive collection of ANSI art

⚡ Intelligent Caching - 6-19x performance improvement (5-20ms load times)

🌐 OS-Wide Cache - Consistent caching across all terminal sessions

🎯 Simple API - Easy-to-use cmdlets with tab completion

⚙️ Configurable Defaults - Persist cache locations and startup behaviour via module configuration

🔄 Auto-Update - Cache automatically invalidates when scripts change

📍 Centralized Storage - Cache stored in %APPDATA%\ColorScripts-Enhanced\cache

Demo

ColorScripts-Enhanced Demo: https://i.imgur.com/FCjqkxn.mp4

Open in new tab since video is too large for github

+ 495 more colorscripts available!

Quick Start (Less Than a Minute)

Install-Module -Name ColorScripts-Enhanced -Scope CurrentUser
Import-Module ColorScripts-Enhanced
Add-ColorScriptProfile              # Optional: add to profile immediately
Show-ColorScript

Requires PowerShell 5.1 or later. PowerShell 7.4+ recommended for best performance and PSResourceGet support.

PowerShell Support

We test every change across Windows, macOS, and Linux. See the full matrix in docs/POWERSHELL-VERSIONS.md.

Platform	PowerShell 5.1	PowerShell 7.x
Windows	✅ Unit tests, module validation	✅ Unit tests, ScriptAnalyzer, help validation
macOS	❌ Not available	✅ Unit tests, ScriptAnalyzer
Linux	❌ Not available	✅ Unit tests, ScriptAnalyzer

We intentionally run ScriptAnalyzer only on PowerShell 7.x because the 5.1 engine applies different rules that conflict with modern cross-platform patterns.

Install a Nerd Font for Custom Glyphs

Several scripts display Nerd Font icons (powerline separators, dev icons, logos). Without a Nerd Font, those glyphs render as blank boxes. Pick one of the patched fonts from nerdfonts.com and set it as your terminal font:

1. Download a font (e.g., Cascadia Code, FiraCode, JetBrainsMono) from the Nerd Fonts releases.
2. Install on Windows: extract the .zip, select the .ttf files, right-click → Install for all users. macOS: brew install --cask font-caskaydia-cove-nerd-font (or double-click in Font Book). Linux: copy the .ttf files to ~/.local/share/fonts (or /usr/local/share/fonts), then run fc-cache -fv.
3. Update your terminal (Windows Terminal, VS Code, Alacritty, etc.) to use the installed Nerd Font for each profile.
4. Verify by running:

Show-ColorScript -Name nerd-font-test

The script will render checkmarks and dev icons when the font is configured correctly.

Installation

Option 1: PowerShell Gallery (Recommended)

The module is published to the PowerShell Gallery, making installation a single command:

# PowerShellGet (Windows PowerShell 5.1 / PowerShell 7)
Install-Module -Name ColorScripts-Enhanced -Scope CurrentUser

# PSResourceGet (PowerShell 7.4+)
Install-PSResource -Name ColorScripts-Enhanced -Scope CurrentUser

# Update to latest release later
Update-Module ColorScripts-Enhanced

💡 Tip: Set Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass if your environment restricts script execution during installation.

Option 2: GitHub Packages (Optional)

If you prefer GitHub Packages (for private mirrors or enterprise environments):

$owner  = 'Nick2bad4u'
$source = "https://nuget.pkg.github.com/$owner/index.json"

Register-PSRepository -Name ColorScriptsEnhanced-GitHub -SourceLocation $source -PublishLocation $source -InstallationPolicy Trusted -PackageManagementProvider NuGet
Install-Module -Name ColorScripts-Enhanced -Repository ColorScriptsEnhanced-GitHub -Scope CurrentUser

Authenticate with a GitHub PAT (Package Read scope) if prompted.

Option 3: Manual Installation

1. Copy the ColorScripts-Enhanced folder to one of your PowerShell module paths:

# See available module paths
$env:PSModulePath -split ';'

# Recommended location (user-specific)
$modulePath = "$env:USERPROFILE\Documents\PowerShell\Modules\ColorScripts-Enhanced"

# Copy the module folder to the destination
Copy-Item -Path ".\ColorScripts-Enhanced" -Destination $modulePath -Recurse -Force

1. Import the module:

Import-Module ColorScripts-Enhanced

1. (Optional) Add to your PowerShell profile for automatic loading:

Add-Content -Path $PROFILE.CurrentUserAllHosts -Value "Import-Module ColorScripts-Enhanced"

Alternatively, run Add-ColorScriptProfile -Scope CurrentUserAllHosts -SkipStartupScript after importing the module.

Option 4: Quick Test (Without Installation)

Import-Module ".\ColorScripts-Enhanced\ColorScripts-Enhanced.psd1"

(Optional) Add to Your PowerShell Profile

Use the built-in helper to import the module (and optionally display a random colorscript) at shell startup:

Add-ColorScriptProfile

Key options:

• Add-ColorScriptProfile -SkipStartupScript -- import the module without showing a script on launch.
• Add-ColorScriptProfile -Scope CurrentUserCurrentHost -- limit to the current host (e.g., just VS Code).
• Add-ColorScriptProfile -Path .\MyCustomProfile.ps1 -- target an explicit profile file.

Usage

Display a Random Colorscript

Show-ColorScript
# or use the alias
scs

Display a Specific Colorscript

Show-ColorScript -Name "mandelbrot-zoom"
# or
scs mandelbrot-zoom

# Use wildcards to target a family of scripts
Show-ColorScript -Name "aurora-*"

List All Available Colorscripts

Show-ColorScript -List
# or
Get-ColorScriptList

# Return objects for automation
$scripts = Get-ColorScriptList -AsObject
$scripts | Select-Object Name, Category, Tags | Format-Table

# Show additional metadata in the table view
Get-ColorScriptList -Detailed

Filter by Category or Tag

# All pattern-based scripts
Get-ColorScriptList -Category Patterns

# Recommended scripts surfaced by metadata
Get-ColorScriptList -Tag Recommended -Detailed

# Display a random recommended script and return its metadata
Show-ColorScript -Tag Recommended -PassThru

Build Cache for Faster Performance

# Cache all colorscripts (recommended)
Build-ColorScriptCache

# Cache specific colorscripts
Build-ColorScriptCache -Name "bars","hearts","arch"

# Force rebuild cache
Build-ColorScriptCache -Force

# Cache every script whose name starts with "aurora-"
Build-ColorScriptCache -Name "aurora-*"

Build-ColorScriptCache caches the entire library by default, so specifying -All is optional. Use -PassThru when you need per-script status objects. Without it you'll just see the concise on-screen summary.

Clear Cache

# Clear all cache files
Clear-ColorScriptCache -All

# Clear specific cache
Clear-ColorScriptCache -Name "mandelbrot-zoom"

# Preview what would be deleted (no files removed)
Clear-ColorScriptCache -Name "mandelbrot-zoom" -DryRun

# Clear caches in an alternate location
Clear-ColorScriptCache -Name "mandelbrot-zoom" -Path 'C:/temp/colorscripts-cache'

# Remove all caches that match a wildcard pattern
Clear-ColorScriptCache -Name "aurora-*" -Confirm:$false

Tip: Set COLOR_SCRIPTS_ENHANCED_CACHE_PATH to redirect cache files to a custom directory for CI or ephemeral test runs.

Persist Defaults with Configuration

# Inspect current configuration (cache path, startup behaviour)
Get-ColorScriptConfiguration

# Persist a custom cache path and disable automatic profile startup
Set-ColorScriptConfiguration -CachePath 'D:/Temp/ColorScriptsCache' -ProfileAutoShow:$false

# Reset everything to defaults
Reset-ColorScriptConfiguration

Configuration is stored in %APPDATA%/ColorScripts-Enhanced/config.json (or the equivalent on macOS/Linux). Set COLOR_SCRIPTS_ENHANCED_CONFIG_ROOT to redirect the configuration location for portable or CI scenarios.

Export Metadata for External Tools

# Emit metadata objects to the pipeline
$metadata = Export-ColorScriptMetadata -IncludeFileInfo -IncludeCacheInfo

# Persist a JSON snapshot for front-end tooling
Export-ColorScriptMetadata -Path ./dist/colorscripts-metadata.json -IncludeFileInfo

Metadata includes categories, tags, descriptions, script paths, and optional cache details--perfect for building dashboards, search interfaces, or gallery listings.

Scaffold a New Colorscript

# Create a new colorscript skeleton in the Scripts directory
$scaffold = New-ColorScript -Name 'my-awesome-script' -GenerateMetadataSnippet -Category 'Artistic' -Tag 'Custom','Demo'

# Inspect metadata guidance for ScriptMetadata.psd1 updates
$scaffold.MetadataGuidance

The scaffolded script includes a UTF-8 template with placeholders so you can paste ANSI art directly. The optional metadata guidance hints at how to categorise the new script in ScriptMetadata.psd1.

Bypass Cache (Force Fresh Execution)

Show-ColorScript -Name "bars" -NoCache

Test the Entire Collection

# Sequential run with metadata-rich summary results
.\ColorScripts-Enhanced\Test-AllColorScripts.ps1 -Filter 'bars' -Delay 0 -SkipErrors

# Parallel run (PowerShell 7+) for faster CI coverage
.\ColorScripts-Enhanced\Test-AllColorScripts.ps1 -Parallel -SkipErrors -ThrottleLimit 4

Lint with PowerShell 7

.\scripts\Lint-PS7.ps1

Commands

Command	Alias	Description
Show-ColorScript	scs	Display a colorscript
Get-ColorScriptList	-	List all available colorscripts
Build-ColorScriptCache	-	Pre-generate cache files
Clear-ColorScriptCache	-	Remove cache files
Add-ColorScriptProfile	-	Append module startup snippet to your profile
Get-ColorScriptConfiguration	-	Inspect persisted defaults (cache path, startup behaviour)
Set-ColorScriptConfiguration	-	Update configuration values and immediately persist them
Reset-ColorScriptConfiguration	-	Restore configuration to factory defaults
Export-ColorScriptMetadata	-	Export metadata and cache info as JSON for external tooling
New-ColorScript	-	Scaffold a new colorscript skeleton with metadata guidance
Install.ps1	-	Optional local installer with -AddToProfile, -SkipStartupScript, -BuildCache

Getting Help

PowerShell uses the Get-Help cmdlet for command documentation. Traditional CLI flags like --help or -h will not work.

# Get basic help
Get-Help Show-ColorScript

# Get detailed help with examples
Get-Help Show-ColorScript -Full

# Get only examples
Get-Help Show-ColorScript -Examples

# Get help for a specific parameter
Get-Help Show-ColorScript -Parameter Name

# Module help
Get-Help about_ColorScripts-Enhanced

Documentation

User Documentation

• Quick Start & Reference
• ANSI Color Guide
• ANSI Conversion Guide
• ANSI Conversion Examples
• Module Summary

Developer Documentation

• Development Guide
• Testing Guide
• Linting Guide
• npm Scripts Reference
• Publishing Guide
• Release Checklist

Project Information

• Support Policy
• Code of Conduct
• Security Policy
• Project Roadmap
• Documentation Index

Contributing

We welcome contributions! Please review CONTRIBUTING.md for:

• Development setup and workflow
• Coding standards and best practices
• How to submit pull requests
• Testing requirements

For development-specific tasks, see the Developer Documentation section above.

Performance

Before Caching

• Simple scripts: 30-50ms
• Complex scripts: 200-400ms

After Caching

• All scripts: 5-20ms
• Improvement: 6-19x faster!

Example Performance Gains

Script	Without Cache	With Cache	Speedup
bars	31ms	5ms	6x
gradient-bars	65ms	8ms	8x
mandelbrot-zoom	365ms	19ms	19x

Cache System

How It Works

1. First Run: Script executes normally and output is cached
2. Subsequent Runs: Cached output is displayed instantly
3. Auto-Invalidation: Cache updates when source script changes
4. OS-Wide: Single cache location works from any directory

Cache Location

The module stores cached output in platform-specific directories:

Windows:

C:\Users\[Username]\AppData\Roaming\ColorScripts-Enhanced\cache\

macOS:

~/Library/Application Support/ColorScripts-Enhanced/cache/

Linux:

~/.cache/ColorScripts-Enhanced/

To find your cache location programmatically:

# Windows
$env:APPDATA\ColorScripts-Enhanced\cache

# macOS
~/Library/Application Support/ColorScripts-Enhanced/cache

# Linux
~/.cache/ColorScripts-Enhanced

Cache Files

• One .cache file per colorscript
• Contains pre-rendered ANSI output
• Average size: ~20KB per file
• Total size: ~4.9MB for 498+ scripts

Examples

Add to PowerShell Profile

Display a random colorscript every time you open PowerShell:

# Edit your profile
notepad $PROFILE.CurrentUserAllHosts

# Add this line:
Import-Module ColorScripts-Enhanced
Show-ColorScript

Create Custom Alias

# Add to profile
Set-Alias -Name cs -Value Show-ColorScript

Build Cache on Module Import

# Add to profile after Import-Module
Import-Module ColorScripts-Enhanced
Build-ColorScriptCache

Available Colorscripts

The module includes 498+ colorscripts including:

• Fractals: mandelbrot-zoom, julia-morphing, barnsley-fern, koch-snowflake
• Patterns: kaleidoscope, wave-pattern, rainbow-waves, gradient-bars
• Characters: pacman, space-invaders, tux, darthvader
• Nature: galaxy-spiral, aurora-storm, crystal-grid, nebula
• Mathematical: fibonacci-spiral, penrose-quasicrystal, hilbert-spectrum
• And many more!

Use Show-ColorScript -List to see all available scripts.

Troubleshooting

Cache Not Working

# Rebuild cache
Build-ColorScriptCache -Force

# Check cache location
explorer "$env:APPDATA\ColorScripts-Enhanced\cache"

Cache Files Locked or Refusing to Delete

# Preview what would be removed without touching the filesystem
Clear-ColorScriptCache -Name 'bars' -DryRun

# Force deletion after closing terminals that might hold locks
Clear-ColorScriptCache -Name 'bars' -Confirm:$false

If a cache file stays locked, close any terminals showing the script, then retry the commands above. As a last resort, specify -Path with a custom cache root and move the cache elsewhere.

Module Not Found

# Verify module path
Get-Module ColorScripts-Enhanced -ListAvailable

# Check PSModulePath
$env:PSModulePath -split ';'

Colorscript Not Displaying

# Try without cache
Show-ColorScript -Name "scriptname" -NoCache

# Check if script exists
Get-ColorScriptList

Icons or glyphs show as squares

# Confirm Nerd Font installation
Show-ColorScript -Name nerd-font-test

# If icons are missing:
# 1\. Install a Nerd Font from https://www.nerdfonts.com/
# 2\. Set your terminal profile to use the installed font
# 3\. Restart the terminal session

Requirements

• PowerShell: 5.1 or higher (PowerShell 7+ recommended)

• Operating System:

  • Windows 10/11
  • macOS 10.13+
  • Linux (Ubuntu, Debian, Fedora, etc.)

• Terminal: ANSI-capable terminal

  • Windows: Windows Terminal, VS Code Terminal, ConEmu
  • macOS: Terminal.app, iTerm2, VS Code Terminal
  • Linux: GNOME Terminal, Konsole, xterm, VS Code Terminal

• Optional: Nerd Font for glyph-heavy scripts like nerd-font-test

Architecture

ColorScripts-Enhanced/
├── ColorScripts-Enhanced.psd1    # Module manifest
├── ColorScripts-Enhanced.psm1    # Main module file
├── Scripts/                       # Colorscript files
│   ├── bars.ps1
│   ├── hearts.ps1
│   ├── mandelbrot-zoom.ps1
│   └── ... (<!-- COLOR_CACHE_TOTAL -->498+<!-- /COLOR_CACHE_TOTAL --> total)
└── README.md                      # This file

%APPDATA%/ColorScripts-Enhanced/
└── cache/                         # Cache files
    ├── bars.cache
    ├── hearts.cache
    └── ... (<!-- COLOR_CACHE_TOTAL -->498+<!-- /COLOR_CACHE_TOTAL --> total)

Contributing

Contributions welcome! When adding new colorscripts:

1. Place .ps1 file in Scripts/ directory
2. Use ANSI escape codes for colors
3. Keep output concise (fits in standard terminal)
4. Test with Show-ColorScript -Name "yourscript" -NoCache
5. Build cache with Build-ColorScriptCache -Name "yourscript"

License

UnLicense License – see LICENSE file for details

Version History

See CHANGELOG.md for detailed version history and release notes.

Latest Release

2025.10.12 - Cross-platform support, enhanced caching, and 498+ colorscripts

Documentation

• 📖 Quick Start & Reference
• 🌈 ANSI Color Guide
• 🧰 ANSI Conversion Guide
• 📋 Module Summary
• 🔧 Development Guide
• 📦 Publishing Guide
• ✅ Release Checklist
• 🤝 Contributing Guidelines
• 🛡️ Security Policy
• 🙌 Code of Conduct
• 🧭 Project Roadmap
• 💬 Support Policy
• 🔄 Changelog

CI/CD & Workflows

• ⚙️ Test Workflow
• � Code Coverage - Automated via Codecov
• �📦 Publish Workflow
• 🤖 Dependabot Updates

Testing

This module uses Pester for testing with code coverage tracking:

# Run all tests
npm run test

# Run tests with coverage report
npm run test:coverage

# Generate HTML coverage report (requires ReportGenerator)
npm run test:coverage:report

# Run tests directly with Pester
Invoke-Pester -Path ./Tests

# Run with coverage using the script
./scripts/Test-Coverage.ps1 -ShowReport

Coverage reports are automatically uploaded to Codecov on every push.

Support

For support options, response targets, and contact channels, review the Support Policy. Bug reports and feature ideas live in the issue tracker.

---

Enjoy the colors and scripts! 🌈✨

ANSI art sourced from:

• DistroTube's shell-color-scripts

• Scott McKendry's ps-color-scripts

• 16colo.rs

• ArtScene Textfiles

• r/ANSIart

• Sixteen Colors Facebook