Skip to content

Clear-ColorScriptCache.md

Latest commit

 

History

History
606 lines (459 loc) · 19 KB

Clear-ColorScriptCache.md

File metadata and controls

606 lines (459 loc) · 19 KB

document type: cmdlet external help file: ColorScripts-Enhanced-help.xml HelpUri: https://github.com/Nick2bad4u/PS-Color-Scripts-Enhanced/blob/main/ColorScripts-Enhanced/en-US/Clear-ColorScriptCache.md Module Name: ColorScripts-Enhanced ms.date: 11/14/2025 PlatyPS schema version: 2024-05-01

Clear-ColorScriptCache

SYNOPSIS

Remove cached colorscript output files.

SYNTAX

All

Clear-ColorScriptCache [-All] [-Path <String>] [-DryRun] [-PassThru] [-Quiet] [-NoAnsiOutput] [-WhatIf] [-Confirm] [<CommonParameters>]

Named

Clear-ColorScriptCache [-Name <String[]>] [-Category <String[]>] [-Tag <String[]>] [-Path <String>] [-DryRun] [-PassThru] [-Quiet] [-NoAnsiOutput] [-WhatIf] [-Confirm] [<CommonParameters>]

__AllParameterSets

Clear-ColorScriptCache [[-Name] <string[]>] [[-Path] <string>] [[-Category] <string[]>] [[-Tag] <string[]>] [-All] [-DryRun] [-PassThru] [-Quiet] [-NoAnsiOutput] [-WhatIf] [-Confirm] [<CommonParameters>]

DESCRIPTION

The Clear-ColorScriptCache cmdlet removes cached output files generated by the ColorScripts-Enhanced module. Cache files store pre-rendered script output to improve performance during subsequent invocations.

You can delete cache files selectively using the -Name parameter with wildcard patterns, or remove all cache files at once with the -All parameter. The cmdlet also supports filtering by -Category and -Tag to target specific subsets of cached scripts.

Unmatched script names report a Missing status in the results. Use -DryRun to preview removal actions without modifying the filesystem, and -Path to target an alternate cache directory (useful for custom cache configurations or CI/CD environments).

Cache files are automatically regenerated the next time Show-ColorScript executes the corresponding script.

For automation scenarios, combine -PassThru to capture structured results, -Quiet to suppress the summary message, or -NoAnsiOutput to emit plain-text summaries without ANSI color codes.

EXAMPLES

EXAMPLE 1

Clear-ColorScriptCache -All -Confirm:$false

Removes every cache file in the default cache directory without prompting for confirmation. This is useful for completely refreshing the cache after module updates or when troubleshooting display issues.

EXAMPLE 2

Clear-ColorScriptCache -Name 'aurora-*' -DryRun

Previews which aurora-themed cache files would be removed without actually deleting them. The output shows the cache files that match the pattern, allowing you to verify the selection before committing to the deletion.

EXAMPLE 3

Clear-ColorScriptCache -Name bars -Path $env:TEMP -Confirm:$false

Clears the cache file for the 'bars' script from a custom cache directory located in the TEMP folder. This is useful when working with the COLOR_SCRIPTS_ENHANCED_CACHE_PATH environment variable or testing alternative cache locations.

EXAMPLE 4

Clear-ColorScriptCache -Category Animation -WhatIf

Shows what would happen if all cache files for scripts in the Animation category were removed. The -WhatIf parameter prevents actual deletion and displays the intended actions.

EXAMPLE 5

Get-ColorScriptList -Tag retro | Clear-ColorScriptCache -DryRun

Uses pipeline input to preview the removal of cache files for all scripts tagged as 'retro'. Combines filtering by tag with a dry-run preview before committing to the deletion.

EXAMPLE 6

Clear-ColorScriptCache -Name 'test-*', 'demo-*' -Confirm:$false

Removes cache files for all scripts whose names begin with 'test-' or 'demo-' without confirmation. Multiple wildcard patterns can be specified as an array.

EXAMPLE 7

# Clean cache and rebuild for optimization
Clear-ColorScriptCache -All -Confirm:$false
New-ColorScriptCache -PassThru | Measure-Object
Write-Host "Cache rebuilt successfully"

Performs a complete cache refresh by clearing all and rebuilding, then shows statistics.

EXAMPLE 8

# Clear old cache entries older than 30 days
$cacheDir = "$env:APPDATA\ColorScripts-Enhanced\cache"
$thirtyDaysAgo = (Get-Date).AddDays(-30)
Get-ChildItem $cacheDir -Filter "*.cache" |
    Where-Object { $_.LastWriteTime -lt $thirtyDaysAgo } |
    ForEach-Object {
        Clear-ColorScriptCache -Name $_.BaseName -Confirm:$false
    }
Write-Host "Old cache files cleaned"

Removes cache files that haven't been updated in more than 30 days.

EXAMPLE 9

# Cache management report
$cacheDir = "$env:APPDATA\ColorScripts-Enhanced\cache"
$beforeCount = @(Get-ChildItem $cacheDir -Filter "*.cache" -ErrorAction SilentlyContinue).Count
Clear-ColorScriptCache -Category Geometric -Confirm:$false
$afterCount = @(Get-ChildItem $cacheDir -Filter "*.cache" -ErrorAction SilentlyContinue).Count
Write-Host "Cleared $($beforeCount - $afterCount) geometric cache files"

Shows statistics about cache clearing operations.

EXAMPLE 10

# Troubleshooting - clear and rebuild specific script
$scriptName = "mandelbrot-zoom"
Clear-ColorScriptCache -Name $scriptName -Confirm:$false
New-ColorScriptCache -Name $scriptName -Force
Show-ColorScript -Name $scriptName

Clears and rebuilds cache for a single script, then displays it for verification.

EXAMPLE 11

# Filter by multiple categories
Clear-ColorScriptCache -Category Geometric,Abstract -DryRun |
    Select-Object CacheFile |
    Measure-Object

Shows how many cache files would be deleted if filtering by multiple categories.

PARAMETERS

-All

Remove every cache file in the target directory. This parameter is mutually exclusive with -Name, -Category, and -Tag. When specified, all filtering parameters are ignored and the entire cache is cleared.

Type: System.Management.Automation.SwitchParameter
DefaultValue: False
SupportsWildcards: false
Aliases: []
ParameterSets:
 - Name: (All)
   Position: Named
   IsRequired: false
   ValueFromPipeline: false
   ValueFromPipelineByPropertyName: false
   ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ""

-Category

Filter the target scripts by category before evaluating cache entries. Only cache files for scripts matching the specified categories will be considered for removal. Accepts an array of category names and can be combined with -Tag for more precise filtering.

Type: System.String[]
DefaultValue: ""
SupportsWildcards: false
Aliases: []
ParameterSets:
 - Name: (All)
   Position: 2
   IsRequired: false
   ValueFromPipeline: false
   ValueFromPipelineByPropertyName: false
   ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ""

-Confirm

Prompts you for confirmation before running the cmdlet. By default, this is enabled to prevent accidental deletion of cache files. Use -Confirm:$false to bypass the confirmation prompt.

Type: System.Management.Automation.SwitchParameter
DefaultValue: True
SupportsWildcards: false
Aliases:
 - cf
ParameterSets:
 - Name: (All)
   Position: Named
   IsRequired: false
   ValueFromPipeline: false
   ValueFromPipelineByPropertyName: false
   ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ""

-DryRun

Preview removal actions without deleting any files. The cmdlet will display which cache files would be removed but will not modify the filesystem. This is useful for verifying your selection criteria before committing to the deletion.

Type: System.Management.Automation.SwitchParameter
DefaultValue: False
SupportsWildcards: false
Aliases: []
ParameterSets:
 - Name: (All)
   Position: Named
   IsRequired: false
   ValueFromPipeline: false
   ValueFromPipelineByPropertyName: false
   ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ""

-PassThru

Return detailed result objects for each cache entry processed. Without this switch, the cmdlet only writes a summary message. Each pass-through record includes the script name, cache file path, status, and any associated error text for further inspection or reporting.

Type: System.Management.Automation.SwitchParameter
DefaultValue: False
SupportsWildcards: false
Aliases: []
ParameterSets:
 - Name: (All)
     Position: Named
     IsRequired: false
     ValueFromPipeline: false
     ValueFromPipelineByPropertyName: false
     ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ""

-Quiet

Suppress the summary message emitted after cache removal completes. Use this switch when running in quiet automation contexts where only structured output (such as -PassThru records, warnings, or errors) should be produced.

Type: System.Management.Automation.SwitchParameter
DefaultValue: False
SupportsWildcards: false
Aliases: []
ParameterSets:
 - Name: (All)
     Position: Named
     IsRequired: false
     ValueFromPipeline: false
     ValueFromPipelineByPropertyName: false
     ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ""

-NoAnsiOutput

Disable ANSI color sequences in the summary output. This is helpful for consoles or log processors that do not interpret ANSI styling, ensuring the summary text remains legible in plain text.

Type: System.Management.Automation.SwitchParameter
DefaultValue: False
SupportsWildcards: false
Aliases:
 - NoColor
ParameterSets:
 - Name: (All)
     Position: Named
     IsRequired: false
     ValueFromPipeline: false
     ValueFromPipelineByPropertyName: false
     ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ""

-Name

Names or wildcard patterns identifying cache files to remove. Accepts pipeline input and property binding from objects with a Name property. Wildcard characters (*, ?) are supported for pattern matching. Mutually exclusive with -All.

Type: System.String[]
DefaultValue: None
SupportsWildcards: true
Aliases: []
ParameterSets:
 - Name: (All)
   Position: 0
   IsRequired: false
   ValueFromPipeline: true
   ValueFromPipelineByPropertyName: true
   ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ""

-Path

Alternate cache directory to operate against. Defaults to the module's standard cache path if not specified. Use this parameter when working with custom cache locations set via the COLOR_SCRIPTS_ENHANCED_CACHE_PATH environment variable, or when managing cache files in alternative directories for testing or CI/CD purposes.

Type: System.String
DefaultValue: None
SupportsWildcards: false
Aliases: []
ParameterSets:
 - Name: (All)
   Position: 1
   IsRequired: false
   ValueFromPipeline: false
   ValueFromPipelineByPropertyName: false
   ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ""

-Tag

Filter the target scripts by metadata tag before evaluating cache entries. Only cache files for scripts with matching tags will be considered for removal. Accepts an array of tag names and can be combined with -Category for more granular control over which cache files are targeted.

Type: System.String[]
DefaultValue: ""
SupportsWildcards: false
Aliases: []
ParameterSets:
 - Name: (All)
   Position: 3
   IsRequired: false
   ValueFromPipeline: false
   ValueFromPipelineByPropertyName: false
   ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ""

-WhatIf

Shows what would happen if the cmdlet runs without actually executing the operation. The cmdlet displays the actions it would perform but does not modify the filesystem. This is a standard PowerShell common parameter that works similarly to -DryRun but follows PowerShell's built-in conventions.

Type: System.Management.Automation.SwitchParameter
DefaultValue: False
SupportsWildcards: false
Aliases:
 - wi
ParameterSets:
 - Name: (All)
   Position: Named
   IsRequired: false
   ValueFromPipeline: false
   ValueFromPipelineByPropertyName: false
   ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ""

CommonParameters

This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.

INPUTS

System.String

You can pipe script names to this cmdlet. Each name will be evaluated for cache file removal based on the specified parameters.

System.String[]

You can pipe an array of script names to this cmdlet. This is particularly useful when combining with Get-ColorScriptList to filter scripts by various criteria before clearing their caches.

System.Management.Automation.PSObject

You can pipe objects with a Name property to this cmdlet. The cmdlet will extract the Name property value and use it to identify cache files for removal.

OUTPUTS

System.Object

Returns status records for each processed cache file. Each output object contains the following properties:

  • Status: The result of the operation (Removed, Missing, DryRun, or Error)
  • CacheFile: The full path to the cache file that was processed
  • Message: Descriptive text explaining the outcome of the operation
  • ScriptName: The name of the script associated with the cache file

ADVANCED USAGE PATTERNS

Cache Maintenance Strategies

Full Cache Rebuild

# Complete cache refresh
Clear-ColorScriptCache -All -Confirm:$false
New-ColorScriptCache -Force
Write-Host "Cache rebuilt successfully"

Targeted Cache Cleaning

# Clear only obsolete entries
Clear-ColorScriptCache -Name "deprecated-*", "test-*" -Confirm:$false

# Verify what would be removed first
Clear-ColorScriptCache -Name "draft-*" -DryRun

Age-Based Cleanup

# Clear cache files older than 60 days
$cacheDir = (Get-ColorScriptConfiguration).Cache.Path
$cutoffDate = (Get-Date).AddDays(-60)

Get-ChildItem $cacheDir -Filter "*.cache" |
    Where-Object { $_.LastWriteTime -lt $cutoffDate } |
    ForEach-Object {
        Clear-ColorScriptCache -Name $_.BaseName -Confirm:$false
    }

Category and Tag Based Cleaning

Clear by Metadata

# Remove caches for experimental category
Clear-ColorScriptCache -Category Experimental -Confirm:$false

# Clear outdated tag
Clear-ColorScriptCache -Tag deprecated -Confirm:$false

# Clear multiple categories at once
Clear-ColorScriptCache -Category @("Demo", "Test", "Draft") -Confirm:$false

Selective Preservation

# Keep only recommended scripts, clear everything else
$keep = Get-ColorScriptList -Tag Recommended -AsObject | Select-Object -ExpandProperty Name
$all = Get-ColorScriptList -AsObject | Select-Object -ExpandProperty Name
$remove = $all | Where-Object { $_ -notin $keep }

$remove | ForEach-Object { Clear-ColorScriptCache -Name $_ -Confirm:$false }

Performance and Reporting

Cache Usage Analysis

# Analyze cache before cleanup
$cacheDir = (Get-ColorScriptConfiguration).Cache.Path
$before = (Get-ChildItem $cacheDir -Filter "*.cache" | Measure-Object -Property Length -Sum).Sum

Clear-ColorScriptCache -Category Demo -DryRun
Write-Host "Current cache size: $([math]::Round($before / 1MB, 2)) MB"

Cleanup Report

# Generate report of cleanup operations
$report = Clear-ColorScriptCache -Name "test-*", "debug-*" -Confirm:$false
$report | Group-Object Status | ForEach-Object {
    Write-Host "$($_.Name): $($_.Count) items"
}

Space Recovery

# Calculate disk space freed
$before = (Get-ChildItem (Get-ColorScriptConfiguration).Cache.Path -Filter "*.cache" | Measure-Object -Property Length -Sum).Sum
Clear-ColorScriptCache -All -Confirm:$false
$after = (Get-ChildItem (Get-ColorScriptConfiguration).Cache.Path -Filter "*.cache" -ErrorAction SilentlyContinue | Measure-Object -Property Length -Sum).Sum

Write-Host "Freed: $([math]::Round(($before - $after) / 1MB, 2)) MB"

CI/CD and Deployment

Pre-Build Cache Cleanup

# Clean build: clear all cache before rebuilding
Clear-ColorScriptCache -All -Confirm:$false
New-ColorScriptCache -Tag Recommended -Force
Write-Host "Cache ready for deployment"

Selective Cache Persistence

# Keep production scripts, clear development
Clear-ColorScriptCache -Tag "development,experimental" -Confirm:$false

# Preserve cache for critical scripts
$critical = @("bars", "arch", "mandelbrot-zoom")
$scripts = Get-ColorScriptList -AsObject | Select-Object -ExpandProperty Name
$toRemove = $scripts | Where-Object { $_ -notin $critical }
$toRemove | ForEach-Object { Clear-ColorScriptCache -Name $_ -Confirm:$false }

Troubleshooting

Verification Workflow

# Verify cache issues and fix
$problemScripts = Get-ColorScriptList -AsObject |
    Where-Object {
        -not (Test-Path "$env:APPDATA\ColorScripts-Enhanced\cache\$($_.Name).cache")
    }

Write-Host "Scripts without cache: $($problemScripts.Count)"
$problemScripts | ForEach-Object {
    Write-Host "Rebuilding: $($_.Name)"
    New-ColorScriptCache -Name $_.Name -Force
}

NOTES

Author: Nick Module: ColorScripts-Enhanced

Cache files are stored with a .cache extension in the module's cache directory. Each cache file corresponds to a single colorscript and contains the pre-rendered ANSI output.

Cache files are automatically regenerated the next time Show-ColorScript executes the corresponding script. This regeneration happens transparently and does not require manual intervention.

The default cache path is exposed via the module's $CacheDir variable and can be overridden using the COLOR_SCRIPTS_ENHANCED_CACHE_PATH environment variable.

When using -DryRun or -WhatIf, the cmdlet will still validate that the cache directory exists and report any issues, but will not perform any deletions.

Filtering by -Category or -Tag requires that the scripts have associated metadata. Scripts without metadata will not match these filters.

Best Practices

  • Always use -DryRun or -WhatIf before destructive operations
  • Use -Confirm:$false only when you're certain about the operation
  • Archive cache before major cleanup operations for recovery
  • Monitor disk space regularly for cache growth
  • Use selective cleaning instead of full clearing when possible
  • Keep track of critical scripts that shouldn't be cleared
  • Schedule automated cleanups during maintenance windows
  • Test cleanup operations in non-production first

Troubleshooting (2)

  • "No cache files found": Use -AsObject to verify which scripts have caches
  • "Permission denied": Verify write access to cache directory
  • "Cache not regenerating": Scripts may have rendering issues; test with -NoCache

RELATED LINKS