Configuring a Console Window Host color theme

Published in Articles on December 6, 2022 by Michiel van Oosterhout ~ 7 min read

We now know that the Windows CLI supports a 4-bit color palette, and how we can configure Console Window Host. In this article we will build on that knowledge to configure a color scheme for Console Window Host.

Color settings

Besides the 4-bit color palette and the default entries used for background (#0) and foreground (#7), Console Window Host supports 3 additional settings related to color. These correspond to a value under the HKCU:\Console key in the Windows Registry:

Use Separate Foreground: DefaultForeground
Use Separate Background: DefaultBackground
Cursor Color: CursorColor

Additional color settings for Console Window Host

By default these settings are configured with the value 0xffffffff which disables the setting. Configuring a specific color value for a setting (e.g. 0x000000ff for the color red) will also enable that setting.

Use separate background and foreground

As we've seen in the article about the Windows CLI color palette, the screen buffer's current text attributes are initially set to the default, after which every cell's character is set to the space character. The default is #0 Black and #7 White for background and foreground color respectively, set in the ScreenColors value (e.g. 0x07) in the Windows Registry.

Setting separate background and foreground color values seems to affect the text attributes of the initial screen buffer, as well as the current text attributes after Console Window Host detects the ^[[0m (reset) sequence.

Windows Command Processor's color command might be aware of the separate background and foreground settings too, as running color 07 seems to change the text attributes for all cells to the separate background and foreground color values, instead of to the color values of entries #0 and #7 of the color palette. Based on some more testing I no longer believe this is the case.

Command-line programs that use the Windows Console API may try to reset the text attributes by setting them to #0 and #7, after which point the separate background and foreground colors are no longer in effect.

Cursor color

Console Window Host renders the cursor using inverted colors (e.g. if the text attibutes specify white text on a blue background, then the text under the cursor will be rendered as black text on a yellow background). This inversion is applied to the bottom 25% or 50%, or to the entire cell (depending on the cursor size and cursor shape settings).

Setting the cursor color changes the rendering mode. With the cursor color set, the cursor obscures the bottom 25% or 50%, or the entire character of the current cell (again depending on the cursor size and cursor shape settings). There are 3 non-legacy cursor shapes that do not obscure the character at all: underscore, vertical bar, and empty box.

Text selection

Console Window Hosts renders text selection using inverted colors. There are no settings to change this.

Configuring a color scheme

A color scheme for Console Window Host is a set of color values for the 4-bit color palette entries, and optionally color values for the separate background and foreground, and a color value for the cursor. The Windows PowerShell script below shows how an alternative color scheme can be configured.

# Partial sequences
$rgb = "$([char]0x1B)[48;2;"
$reset = "$([char]0x1B)[0"

# Define the color palette entry values for the Argonaut color scheme
$colors = @(
    @{ Name = "Black";                          Red = 0x23; Green = 0x23; Blue = 0x23 }
    @{ Name = "Blue";                           Red = 0x00; Green = 0x8d; Blue = 0xf8 }
    @{ Name = "Green";                          Red = 0x8c; Green = 0xe1; Blue = 0x0b }
    @{ Name = "Aqua/Cyan";                      Red = 0x00; Green = 0xd8; Blue = 0xeb }
    @{ Name = "Red";                            Red = 0xff; Green = 0x00; Blue = 0x0f }
    @{ Name = "Purple/Magenta";                 Red = 0x6d; Green = 0x43; Blue = 0xa6 }
    @{ Name = "Yellow";                         Red = 0xff; Green = 0xb9; Blue = 0x00 }
    @{ Name = "White";                          Red = 0xcc; Green = 0xcc; Blue = 0xcc }
    @{ Name = "Gray/Bright Black";              Red = 0x44; Green = 0x44; Blue = 0x44 }
    @{ Name = "Light/Bright Blue";              Red = 0x00; Green = 0x92; Blue = 0xff }
    @{ Name = "Light/Bright Green";             Red = 0xab; Green = 0xe1; Blue = 0x5b }
    @{ Name = "Light Aqua/Bright Cyan";         Red = 0x67; Green = 0xff; Blue = 0xf0 }
    @{ Name = "Light/Bright Red";               Red = 0xff; Green = 0x27; Blue = 0x40 }
    @{ Name = "Light Purple/Bright Magenta";    Red = 0x9a; Green = 0x5f; Blue = 0xeb }
    @{ Name = "Light/Bright Yellow";            Red = 0xff; Green = 0xd2; Blue = 0x42 }
    @{ Name = "Bright White";                   Red = 0xff; Green = 0xff; Blue = 0xff }
)

# Ensure the registry key exists
$defaultsPath = "HKCU:\Console"
if (-not (Test-Path -Path $defaultsPath))
{
    $key = New-Item -Force -ItemType Directory -Path $defaultsPath
}

# Set the color values for Console Window Host's 4-bit color palette
Write-Host "Configuring color scheme..." -NoNewline
for ($i = 0; $i -lt $colors.Count; $i++) {
    $color = $colors[$i]

    $red = $color.Red
    $green = $color.Green
    $blue = $color.Blue

    $name = "ColorTable{0:D2}" -f $i
    $value = $red + ($green -shl 8) + ($blue -shl 16)    

    Write-Host (" {0}$red;$green;${blue}m  {1}m " -f $rgb,$reset) -NoNewline
    $value = New-ItemProperty -Force -Name $name -Path $defaultsPath -PropertyType "DWord" -Value $value
}

# Separate the color palette colors from the additional colors
Write-Host "+" -NoNewline

# Define the color values for the additional color values
$settings = @(
    @{ Name = "DefaultBackground"; Red = 0x0e; Green = 0x10; Blue = 0x19 }
    @{ Name = "DefaultForeground"; Red = 0xff; Green = 0xfa; Blue = 0xf4 }
)

# Configure the additional color settings
for ($i = 0; $i -lt $settings.Count; $i++) {
    $setting = $settings[$i]

    $red = $setting.Red
    $green = $setting.Green
    $blue = $setting.Blue

    $name = $setting.Name
    $value = $red + ($green -shl 8) + ($blue -shl 16)

    Write-Host (" {0}$red;$green;${blue}m  {1}m " -f $rgb,$reset) -NoNewline
    $value = New-ItemProperty -Force -Name $name -Path $defaultsPath -PropertyType "DWord" -Value $value
}

Write-Host " OK"

The scheme is based on Argonaut, with the color value for White changed from 0xffffff (same as the value for Bright White) to 0xcccccc (taken from the default Campbell theme), and the cursor color not set.

PowerShell

Windows PowerShell uses a module called PSReadLine that parses the command line as it is being edited to provide color highlighting. It uses terminal sequences for color highlighting, but by default limits itself to the 4-bit color palette. The specific color palette entries (or 24-bit color values) it uses can be configured.

The Get-PSReadLineOption cmdlet returns an object with properties such as CommandColor and OperatorColor corresponding to the color settings. By default the OperatorColor and ParameterColor are set to #0 Black, which makes them hard to read on a dark background. The Windows PowerShell script below configures different color palette entries for some of PSReadLine's options to improve legibility.

# Sequence introducer
$sgr = "$([char]0x1B)["

# Define the sequence numbers for background and foreground colors
$colors = @{
    BlackBackground  = 40; BlackForeground  = 30
    BlueBackground   = 44; BlueForeground   = 34
    GreenBackground  = 42; GreenForeground  = 32
    AquaBackground   = 46; AquaForeground   = 36
    RedBackground    = 41; RedForeground    = 31
    PurpleBackground = 45; PurpleForeground = 35
    YellowBackground = 43; YellowForeground = 33
    WhiteBackground  = 47; WhiteForeground  = 37

    GrayBackground        = 100; GrayForeground        = 90
    LightBlueBackground   = 104; LightBlueForeground   = 94
    LightGreenBackground  = 102; LightGreenForeground  = 92
    LightAquaBackground   = 106; LightAquaForeground   = 96
    LightRedBackground    = 101; LightRedForeground    = 91
    LightPurpleBackground = 105; LightPurpleForeground = 95
    LightYellowBackground = 103; LighYellowForeground  = 93
    BrightWhiteBackground = 107; BrightWhiteForeground = 97
}

# Get the options to configure them
$options = Get-PSReadLineOption
$options.OperatorColor = "$($sgr)$($colors.LightAquaForeground)m"
$options.ParameterColor = "$($sgr)$($colors.LightBlueForeground)m"

Important! This script should be added to your PowerShell profile. To create and then edit your PowerShell profile:

$directoryPath = Split-Path -Path $Profile -Parent
If (-not (Test-Path -Path $directoryPath))
{
    $directory = New-Item -ItemType Directory -Path $directoryPath
}
If (-not (Test-Path -Path $profile))
{
    $file = New-Item -ItemType File -Path $profile
}
& notepad $profile

To allow the code in your PowerShell profile to be executed, you need to set the execution policy in an elevated Windows PowerShell session:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Force

When you've added the script to your Windows PowerShell profile, and allowed the execution of local scripts, PSReadLine will always use the configured colors.

Summary

Configuring a color scheme for Console Window Host requires some knowledge of the old 4-bit color palette as well as an understanding of the more recently introduced color settings. There are lots of color schemes available online, just make sure you adjust the color values from RGB to BGR. After configuring a color scheme you may want to adjust the PSReadLine options to ensure PowerShell command lines remain legible.