PSCalendar Overview

This module contains a few functions for displaying a calendar in the PowerShell console. The primary function is based on code originally published by Lee Holmes at http://www.leeholmes.com/blog/2008/12/03/showing-calendars-in-your-oof-messages/. However, v2.0.0 of this module contains a complete rewrite of the core functions.

Installation

You can install this module from the PowerShell Gallery.

Install-PSResource PSCalendar

Installing this module will also install the Microsoft.PowerShell.ThreadJob module from the PowerShell Gallery, as that is module dependency if you want to use Show-GuiCalendar. If you have the legacy ThreadJob module installed, you might get a warning if you install this module with Install-Module. If you do, run Install-Module PSCalendar -AllowClobber. You shouldn't see this error if you install using Install-PSResource.

The commands in this module have been tested on PowerShell 7 both under Windows and Linux and there is no reason these commands should not work. Commands and aliases that are incompatible with non-Windows platforms will be handled on a per command basis.

After installing the module, you can view a local PDF version of this file by running Show-PSCalendarHelp.

Note: If you are upgrading to v2.0.0 or later of this module, and have older versions installed, it is recommended that you uninstall the older versions.

Module Commands

| Name | Alias | Synopsis | |-----------------------------|-------|-----------------------------------------------------------| | Export-PSCalendarConfiguration | Save-PSCalendarConfiguration | Save the current calendar configuration settings to a file. | | Get-PSCalendar | cal,Get-Calendar | Displays a visual representation of a calendar. | | Get-MonthName | mon | Get the list of month names. | | Get-NCalendar | ncal | Display a Linux-style ncal calendar. | | Get-PSCalendarConfiguration | | Get the current PSCalendar ANSI configuration. | | Set-PSCalendarConfiguration | | Modify the PSCalendar ANSI configuration. | | Show-PSCalendar | scal,Show-Calendar | Display a colorized calendar month in the console. | | Show-GuiCalendar | gcal | Display a WPF-based calendar. | | Show-PSCalendarHelp | | Display a help PDF file for the PSCalendar module. |

Here are a few details are the commands you are most likely to use. in v2.11.0 Get-Calendar and Show-PSCalendar have been renamed to Get-PSCalendar and Show-PSCalendar. The old names are now aliases for the new commands. This was done to make the command names more consistent with this module. This change shouldn't break any existing scripts or commands that use the old names.

Note that not all screen shots have been updated to reflect the latest version of the module.

Get-PSCalendar

The commands in this module have been updated to take advantage ANSI escape sequences. The main function, Get-PSCalendar, will display the current month in the console, highlighting the current date with an ANSI escape sequence. By default, weekend days are also highlighted.

But you can also specify a calendar by month and year.

In this example you can see that I specified dates to highlight. Or you can specify a range of months.

In v2.10.0 you can now specify a range of months by calendar quarter. The default is the current year.

The function should be culturally aware. The commands in this module that have a -Month parameter should autocomplete to culture-specific month names.

There is a similar autocompletion for -Year that begins with the current year and then the next 5 years. Although nothing prevents you from entering any year you want.

Highlighting Dates

You can specify dates to highlight using the -HighlightDate parameter. You can pass an array of dates, or a single date with multiple dates separated by commas. The dates should be in the culture-specific short date format. You can also specify just the day of the month, and the current month and year will be used.

If you specify a string, the date will be displayed using the ANSI sequence defined in Get-PSCalendarConfiguration for highlight. However, beginning with v2.11.0, you can also pass a hashtable where the key is the date to highlight and the value is the ANSI sequence to use.

$h = @{
  "8/1/2025" = "`e[1;3;38;5;213m"
  "8/13/2025" = $PSStyle.Foreground.BrightYellow
  "8/18/2025" = $PSStyle.Foreground.BrightYellow
  "8/9/2025" = $PSStyle.Foreground.BrightMagenta
  "8/29/2025" = $PSStyle.Foreground.BrightRed
}
Get-PSCalendar -HighLightDate $h

You can use any ANSI sequence or a $PSStyle value.

Show-PSCalendar

In previous versions of this module, there was a command called Show-PSCalendar which wrote a colorized version of the calendar to the host using Write-Host. This command has been rewritten and now is essentially a wrapper for Get-PSCalendar. The primary difference is that you can position the calendar with this command.

$pos = [System.Management.Automation.Host.Coordinates]::new(72,0)
$h = "7/4/2025","7/14/2025"
Show-PSCalendar -HighLightDate $h -Position $pos -Month July

A Console Calendar Prompt

One way you might want to use this is in your PowerShell console. You can use the prompt function like this:

#requires -modules "PSCalendar"

Function prompt {
  #define a buffer cell fill
  $fill = [system.management.automation.host.buffercell]::new(" ",$host.UI.RawUI.BackgroundColor,$host.UI.RawUI.BackgroundColor,"complete")

  #define a rectangle with an upper left corner X distance from the edge
  $left =$host.UI.RawUI.WindowSize.width - 42

  #need to adjust positioning based on buffer size of the console
  #is the cursor beyond the window size, ie have we scrolled down?
    if ($host.UI.RawUI.CursorPosition.Y -gt $host.UI.RawUI.WindowSize.Height) {
        $top = $host.UI.RawUI.CursorPosition.Y - $host.UI.RawUI.WindowSize.Height
    }
    else {
        $top = 0
    }
  #    System.Management.Automation.Host.Rectangle new(int left, int top, int right, int bottom)
  $r = [System.Management.Automation.Host.Rectangle]::new($left, 0, $host.UI.RawUI.WindowSize.width,$top+10)

  #clear the area for the calendar display
  $host.UI.RawUI.SetBufferContents($r,$fill)

  #show the calendar in the upper right corner of the console
  $pos = [system.management.automation.host.coordinates]::new($left,0)
  Show-PSCalendar -Position $pos

  "PS $($executionContext.SessionState.Path.CurrentLocation)$('>' * ($nestedPromptLevel + 1)) ";

# .Link
# https://go.microsoft.com/fwlink/?LinkID=225750
# .ExternalHelp System.Management.Automation.dll-help.xml
}

Assuming the width of your console is at least 120, this code should work. Otherwise, you might need to tweak the positioning. This should also work in Windows Terminal. If you add some highlighted dates using $PSDefaultParameterValues, then you'll have a calendar right in front of you.

Note that any command output may be truncated because of the calendar display. This prompt function works as expected when using the Windows Terminal. The function needs work to behave as expected in a traditional PowerShell console where you might have a large buffer for scrolling.

Show-GuiCalendar

Finally, you can display a graphical calendar using a Windows Presentation Foundation (WPF) based script.

This command is not supported on non-Windows platforms.

The function runs the calendar-related code in a separate runspace so it does not block your prompt. You can display up to 3 months and specify dates to highlight. You cannot customize the highlight style.

Show-GuiCalendar 12/2025 2/2026 -highlight 12/24/25,12/25/25,12/31/25,1/1/26,1/18/26,2/14/26,2/22/26

The calendar form is transparent. But you should be able to click on it to drag it around your screen. You can also use the + and - keys to increase or decrease the calendar's opacity. Be aware that if you close the PowerShell session that launched the calendar, the calendar too will close.

Beginning with module version 2.2.0 you can also customize the calendar background with an image:

Show-GuiCalendar -BackgroundImage D:\images\blue-robot-ps-thumb3.png -Stretch Fill -FontWeight DemiBold

![blue-psrobot-calendar](images/calendar-background.pn