A Guide to Customising the Windows Terminal

The Windows Terminal app is available on the Microsoft Store. If you open the store and search for “Windows terminal”, it should be the first item on the list. It’s also available on its GitHub releases page but you will miss out on automatic updates if you install it from there. You can also install the preview version if you want to be on the bleeding edge of features.

Once installed, launch the terminal. The interface is quite straightforward with tabs at the top and a dropdown menu for switching between the different profiles. By default, you get a profile for PowerShell, the Command prompt, any WSL distributions you have installed, and Microsoft Azure.

You can open the terminal settings through the dropdown menu or by pressing Ctrl + , on your keyboard. From v1.7, the JSON file that contains all the terminal settings is no longer open by default as was the case in earlier releases. A new settings UI has been developed and it’s now the default way to manage your preferences although it’s only a frontend for the underlying JSON file which can be still be accessed by pressing Ctrl + Shift + ,.

Launching the terminal with a keyboard shortcut

The easiest way to bind the Windows terminal to a keyboard shortcut is to pin it to the task bar and press the Win key plus the number corresponding to the position of the program on the taskbar. For example, Win + 3 launches or focuses the terminal window on my computer.

I don’t like this method because it flashes the taskbar on the screen briefly while the switch is being made which I find distracting. Fortunately, there is a better way to do this in Windows Terminal v1.9 or later through the global summon action.

You can set it up by opening the settings JSON file with Ctrl + Shift + ,, then find the actions property and add the following object to it:

"actions": [
  {
    "command": {
      "action": "globalSummon"
    },
    "keys": "alt+t"
  }
]

Once that’s done, you’ll be able to bring up the Windows terminal with a keystroke. The snippet above uses Alt + t, but you can change it to your preferred key binding. Ensure to read the docs to learn how to customise it further.

Launching the terminal from Windows Explorer

You can launch the Windows Terminal from the File Explorer by typing wt and Enter in the address bar. This will launch a new terminal window in your default user directory. To specify the current directory instead, use wt -d ..

Additionally, you can right click on a directory in File Explorer and select “Open in Windows Terminal”. This will launch Windows Terminal with your default profile in the selected directory.

Customising the default profile

The default profile is what appears when you launch a Windows terminal instance or open a new tab. It should be initially set to a Windows PowerShell profile but you can easily change it to some other profile such as the one for your preferred WSL distribution. Achieving this can be done by updating the value of the defaultProfile property in the settings.json file with the guid of your preferred profile. It can also be changed through the settings UI as shown below:

Customising the tab switcher

From v1.5, the Windows terminal tab switcher displays currently open tabs in a vertical list, navigable with the keyboard or mouse. This feature had to be activated in earlier versions by setting the useTabSwitcher property (now deprecated) to true.

You can opt out of the tab switcher experience by setting tabSwitcherMode to false or "disabled". When the tab switcher is disabled, pressing ctrl + tab or ctrl + shift + tab will switch tabs in a similar manner to most web browsers. If you want to control the order of the tabs in the tab switcher, you can set tabSwitcherMode to mru or inOrder which will list the tabs either in most recently used order or in order of their layout in the terminal.

// Enables the tab switcher
"tabSwitcherMode": "mru",
"tabSwitcherMode": "inOrder"

// Disables the tab switcher
"tabSwitcherMode": "disabled"

You can also search your open tabs with the tabSearch command but you have to create a binding for it first. This is useful if you usually have several tabs open at same time.

{
    "actions": [
        { "command": "tabSearch", "keys": "ctrl+t" }
    ]
}

Customising the profile settings

The profile settings can be accessed through the profiles property in the settings.json file. If you want any setting to apply to all profiles, add it to the defaults property. Otherwise, add it to the relevant object in the list array.

"defaults":
{
    // SETTINGS TO APPLY TO ALL PROFILES
},
"list":
[
    // PROFILE OBJECTS
]

Changing the starting directory

By default, the starting directory for all shells is the Windows User directory ("%USERPROFILE%"), but you probably want this to be your Linux home directory in your WSL profiles. You can add the startingDirectory property to your WSL distribution profile object as shown below to override this setting.

{
    "guid": "{07b52e3e-de2c-5db4-bd2d-ba144ed6c273}",
    "hidden": false,
    "name": "Ubuntu-20.04",
    "source": "Windows.Terminal.Wsl",
    "startingDirectory": "\\\\wsl$\\Ubuntu-20.04\\home\\<username>"
}

Hiding a profile

To hide a profile from the dropdown menu, set the hidden property on the profile object to true.

{
    "guid": "{b453ae62-4e3d-5e58-b989-0a998ec441b8}",
    "hidden": true,
    "name": "Azure Cloud Shell",
    "source": "Windows.Terminal.Azure"
}

Turning off the scroll bar

If you primarily use a terminal multiplexer like tmux, you may want to turn off the scroll bar for your WSL profile by setting the scrollbarState option to hidden.

{
    "guid": "{07b52e3e-de2c-5db4-bd2d-ba144ed6c273}",
    "hidden": false,
    "name": "Ubuntu-20.04",
    "source": "Windows.Terminal.Wsl",
    "startingDirectory": "\\\\wsl$\\Ubuntu-20.04\\home\\<username>",
    "scrollbarState": "hidden"
}

You can read the documentation for the profile settings to learn about all the options available to you.

Customising the background

It’s possible to customise the Windows terminal with background images. The backgroundImage property can be set to an image URL, a local file path or the desktopWallpaper string (from v1.5), and the image in question may be of JPEG, PNG or GIF formats. You also have control over related settings such as opacity, alignment, and stretching. These settings can be configured globally for all profiles or per profile.

{
    "backgroundImage": "https://images.unsplash.com/photo-1554110397-9bac083977c6?ixid=MXwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHw%3D&ixlib=rb-1.2.1&auto=format&fit=crop&w=2100&q=80",
    "backgroundImageOpacity": 0.4,
    "backgroundImageAlignment": "center"
}

The terminal also supports the acrylic effect in Windows 10 which can be enabled by setting useAcrylic to true. The transparency of the effect can be controlled with acrylicOpacity (accepts a floating point between 0 and 1). You can use these settings with or without a background image.

{
    "useAcrylic": true,
    "acrylicOpacity": 0.5
}

Customising the colour scheme

The terminal comes with a few colour schemes that you can choose from. They are accessible via the color schemes menu. You can choose your preferred global colour scheme from this menu, or add new ones if you don’t like any of the defaults.

If you prefer to set a different colour scheme per profile, the relevant setting is under the Appearance tab for each profile.

The same can be achieved in the settings.json file through the colorScheme option. This option can be set globally for all profiles or per profile.

{
    "guid": "{61c54bbd-c2c6-5271-96e7-009a87ff44bf}",
    "name": "Windows PowerShell",
    "commandline": "powershell.exe",
    "colorScheme": "Campbell Powershell",
    "useAcrylic": true,
    "acrylicOpacity": 0.9
}

Adding custom colour schemes is also easier through the settings.json file. All you need to do is define the colour scheme object in the schemes array section of the file. A great place to source for colour schemes is the Windows Terminal Themes website. You can preview each available theme and, when you find one you like, click the Get theme button to copy its JSON object to your clipboard.

Place the JSON object in the schemes array, then set the colorScheme property to the theme name (or use the settings UI to set the theme). The new theme should take effect once you save the file.

{
    "schemes": [
        {
            "name": "AdventureTime",
            "black": "#050404",
            "red": "#bd0013",
            "green": "#4ab118",
            "yellow": "#e7741e",
            "blue": "#0f4ac6",
            "purple": "#665993",
            "cyan": "#70a598",
            "white": "#f8dcc0",
            "brightBlack": "#4e7cbf",
            "brightRed": "#fc5f5a",
            "brightGreen": "#9eff6e",
            "brightYellow": "#efc11a",
            "brightBlue": "#1997c6",
            "brightPurple": "#9b5953",
            "brightCyan": "#c8faf4",
            "brightWhite": "#f6f5fb",
            "background": "#1f1d45",
            "foreground": "#f8dcc0"
        }
    ]
}

Prettifying your terminal prompt with Starship

Starship provides a customised command prompt experience that displays some handy information to give you context of what you’re doing. It supports all the popular shells on Linux, macOS, and Windows including Bash, Fish, Zsh, Powershell, and others, making it possible to get a consistent prompt even if you often switch between different shells.

Before you install Starship, you need to make sure a Nerd font is installed on your computer first to prevent broken glyphs from ruining your prompt. A good option is Cascadia Code (the default Windows terminal font) which can be downloaded from its GitHub releases page. Once downloaded, extract the zip, and install all the font files contained in the ttf/static folder.

Next, change the fontFace property in your profile settings to Cascadia Code PL.

{
    "fontFace": "Cascadia Code PL"
}

Afterwards, go ahead and install Starship by following the instructions for your preferred shell. Once you’re done, create a configuration file in the appropriate directory (~/.config on Linux):

mkdir -p ~/.config && touch ~/.config/starship.toml

Open the starship.toml file, and paste in the following contents:

add_newline = false

[character]
success_symbol = "[⚡](bold green) "
error_symbol = "[❌](bold red) "

[aws]
disabled = true

[time]
disabled = true

[cmd_duration]
disabled = true

[directory]
truncation_length = 8

[hostname]
disabled = true

[nodejs]
symbol = "🤢"

[battery]
full_symbol = "🔋 "
charging_symbol = "⚡️ "
discharging_symbol = "💀 "
disabled = false

[git_status]
conflicted = "🚩"
ahead = "💨"
behind = "😰"
diverged = "😵"
untracked = "🤷"
stashed = "📦"
modified = "📝"
staged = '[++\($count\)](green)'
renamed = "👅"
deleted = "💥"

[shell]
fish_indicator = "🦈"
bash_indicator = "🌞"
disabled = false

The above represents my current configuration which should give you a prompt that looks similar to the previous screenshot. You can head over to the Starship docs to learn more about the available options, then tweak your configuration file as needed.

Splitting panes for multiple shells at once

The Windows terminal supports splitting a tab into multiple panes. This makes it easy to multitask without having to switch tabs. I use tmux for this purpose in WSL so it’s not something I rely on often, but it’s handy to have especially if you need to work in PowerShell or cmd.exe for example.

The default shortcuts to split a pane horizontally and vertically are Alt + Shift + - and Alt + Shift + = respectively. You can also split a pane using the command palette which can be accessed with Ctrl + Shift + p:

If you hold down the Alt key and press the new tab button on one of the profiles in the terminal dropdown menu, it would also auto split the active window or pane. To switch focus between panes, hold down Alt and use your arrow keys or click on the desired pane. Resizing the focused pane is done by holding down Alt + Shift and one of the arrow keys. Closing a pane can be done with Ctrl + Shift + W.

Customising the hotkeys

All the hotkeys for Windows Terminal commands can be customised through the actions property (formerly keybindings) in the settings.json file. If you inspect the defaults.json file for your terminal (by holding the Alt key while clicking the Settings menu), you’ll see all the default key bindings organised in several categories in the root level actions array.

You can add a new hotkey for an action by copying the relevant binding object from the defaults.json file to the settings.json file, and changing the keys property in the object. If you modify the defaults.json file directly, your changes will be lost when the program updates. For example, the bindings for splitting panes can be customised as shown below:

{
  "actions": [
    { "command": { "action": "splitPane", "split": "vertical" }, "keys": "alt+v" },
    { "command": { "action": "splitPane", "split": "horizontal" }, "keys": "alt+h" }
  ]
}

The above lines add new bindings for the splitPane action, but the original bindings will remain active. To remove a default key binding, assign the key to the unbound command as shown below:

{
  "actions": [
    { "command": { "action": "splitPane", "split": "vertical" }, "keys": "alt+v" },
    { "command": { "action": "splitPane", "split": "horizontal" }, "keys": "alt+h" },
    { "command": "unbound", "keys": "alt+shift+-" },
    { "command": "unbound", "keys": "alt+shift+=" }
  ]
}

Windows terminal also gives you the ability to send input commands to your shell with a key stroke. This is handy for commonly used commands. Here’s an example that binds Alt + G to sending a command that navigates to the root of the working tree in a git repo:

{
  "actions": [
      { "command": {"action": "sendInput", "input": "cd (git rev-parse --show-toplevel)"}, "keys": "alt+g" }
  ]
}

The full list of commands and their options can be found in the actions documentation.

Setting up custom SSH profiles

It can be handy to automatically SSH into remote machines through the Windows Terminal. This can be done by setting up a new custom profile per machine.

{
    "guid":  "{4b8d0cfe-e8be-4ae6-a4ad-88efd65b0880}",
    "hidden":  false,
    "name":  "Failed Experiments",
    "commandline":  "wsl ssh user@localhost",
    "icon": "🤡"
}

The guid field must be unique amongst the profiles. You can make changes to an exisiting one or generate it online. Regarding the icon, you can use an emoji character (v1.5 or later) or type the path to a suitable image file. Once you save the settings file, you should see your new entry similar to the screenshot below.

Once you click the entry, it will automatically connect to the remote server in your preferred Linux distribution.

Customising the startup layout

Windows terminal launches with a single tab and a single pane using your default profile, but you can customise this behaviour through command line arguments. Here’s an example that launches the terminal with a custom layout of three split panes in a single tab. The panes are running a WSL profile, a PowerShell profile, and a Command Prompt profile respectively.

wt; split-pane -p "Windows PowerShell"

Here’s a breakdown of the above command:

• wt on its own launches a new window with a single tab and a single pane with the default profile. Each command after wt must be separated with a semicolon.
• split-pane splits the current pane into two defaulting to auto if you don’t specify a direction (-H or -V). The -p flag allows you to specify the the type of profile you want to open by name or guid.

After you have defined your preferred startup layout, you can bind it to a hotkey using AutoHotkey or create a new Windows shortcut and pin it to your desktop or taskbar.

Conclusion

In this post, we discussed several ways to customise the Windows Terminal. I hope it has helped you improve your workflow and productivity on the command line. If you have any more tips, please share them in the comments section below.

Thanks for reading, and happy coding!

• #windows terminal
• #wsl
• #powershell