Custom actions in Windows Terminal

Important

As of Windows Terminal version 1.4, the keybindings array has been renamed to actions inside the settings.json file. Support for the keybindings array still exists for backward compatibility, however the terminal will not automatically rename keybindings to actions inside your settings.json file.

You can create custom actions inside Windows Terminal that give you control of how you interact with the terminal. These actions will automatically be added to the command palette.

Action formats

Actions can be structured in the following formats:

Commands without arguments

{ "command": "commandName", "keys": "modifiers+key" }

For example, this default setting uses the shortcut key alt+f4 to close the terminal window:

{ "command": "closeWindow", "keys": "alt+f4" }

Commands with arguments

{ "command": { "action": "commandName", "argument": "value" }, "keys": "modifiers+key" }

For example, this default setting uses the shortcut key ctrl+shift+1 to open a new tab in the terminal based on whichever profile is listed first in your dropdown menu (typically this will open the PowerShell profile):

{ "command": { "action": "newTab", "index": 0 }, "keys": "ctrl+shift+1" }


Action properties

Actions can be constructed using the following properties.

Command

This is the command executed when the associated keys are pressed.

Property name: command

Necessity: Required

Accepts: String

Keys

This defines the key combinations used to call the command. Keys can have any number of modifiers with one key. Accepted modifiers and keys are listed below.

If the action does not have keys, it will appear in the command palette but cannot be invoked with the keyboard.

Property name: keys

Necessity: Optional

Accepts: String or array[string]

Action

This adds additional functionality to certain commands.

Property name: action

Necessity: Optional

Accepts: String

Name

This sets the name that will appear in the command palette. If one isn't provided, the terminal will attempt to automatically generate a name.

Property name: name

Necessity: Optional

Accepts: String

Icon

This sets the icon that displays within the command palette.

Property name: icon

Necessity: Optional

Accepts: File location as a string, or an emoji



Accepted modifiers and keys

Modifiers

ctrl+, shift+, alt+

Note

The Windows key is not supported as a modifier.

Modifier keys

Type Keys
Function and alphanumeric keys f1-f24, a-z, 0-9
Symbols `, plus, -, =, [, ], \, ;, ', ,, ., /
Arrow keys down, left, right, up, pagedown, pageup, pgdn, pgup, end, home
Action keys tab, enter, esc, escape, space, backspace, delete, insert, app, menu
Numpad keys numpad_0-numpad_9, numpad0-numpad9, numpad_add, numpad_plus, numpad_decimal, numpad_period, numpad_divide, numpad_minus, numpad_subtract, numpad_multiply

Note: = and plus are equivalents. The latter must not be confused with numpad_plus.


Application-level commands

Close window

This closes the current window and all tabs within it. If confirmCloseAllTabs is set to true, a confirmation dialog will appear to ensure you'd like to close all your tabs. More information on this setting can be found on the Global settings page.

Command name: closeWindow

Default binding:

{ "command": "closeWindow", "keys": "alt+f4" }

Windows Terminal confirm close all tabs

Find

This opens the search dialog box. More information on search can be found on the Search page.

Command name: find

Default binding:

{ "command": "find", "keys": "ctrl+shift+f" }

Open the dropdown

This opens the dropdown menu.

Command name: openNewTabDropdown

Default binding:

{ "command": "openNewTabDropdown", "keys": "ctrl+shift+space" }

Open settings files

This opens either the default or custom settings files. Without the target field, this will open the settings.json file.

Command name: openSettings

Default binding:

{ "command": "openSettings", "keys": "ctrl+," },
{ "command": { "action": "openSettings", "target": "defaultsFile" }, "keys": "ctrl+alt+," },

Actions

Name Necessity Accepts Description
target Optional "settingsFile", "defaultsFile", "allFiles" The settings file to open.

Toggle full screen

This allows you to switch between full screen and default window sizes.

Command name: toggleFullscreen

Default bindings:

{ "command": "toggleFullscreen", "keys": "alt+enter" },
{ "command": "toggleFullscreen", "keys": "f11" }

Toggle focus mode

This allows you to enter "focus mode", which hides the tabs and title bar.

Command name: toggleFocusMode

Default bindings:

{ "command": "toggleFocusMode" }

Toggle always on top mode

This allows you toggle the "always on top" state of the window. When in "always on top" mode, the window will appear on top of all other non-topmost windows.

Command name: toggleAlwaysOnTop

Default bindings:

{ "command": "toggleAlwaysOnTop" }

Send input

Send arbitrary text input to the shell. As an example the input "text\n" will write "text" followed by a newline to the shell.

ANSI escape sequences may be used, but escape codes like \x1b must be written as \u001b. For instance "\u001b[A" will behave as if the up arrow button had been pressed.

Command name: sendInput

Default bindings:

This command is not currently bound in the default settings.

{ "command": { "action": "sendInput", "input": "\u001b[A" }, "keys": "" }

Actions

Name Necessity Accepts Description
input Required String The text input to feed into the shell.


Tab management commands

Close tab

This closes the current tab.

Command name: closeTab

Close all other tabs

This closes all tabs except for the one at an index. If no index is provided, use the focused tab's index.

Command name: closeOtherTabs

Default binding:

{ "command": "closeOtherTabs" }

Actions

Name Necessity Accepts Description
index Optional Integer Position of the tab to be kept open.

Close tabs after index

This closes the tabs following the tab at an index. If no index is provided, use the focused tab's index.

Command name: closeTabsAfter

Default binding:

{ "command": "closeTabsAfter" }

Actions

Name Necessity Accepts Description
index Optional Integer Position of the last tab to be kept open.

Duplicate tab

This makes a copy of the current tab and opens it.

Command name: duplicateTab

Default binding:

{ "command": "duplicateTab", "keys": "ctrl+shift+d" }

New tab

This creates a new tab. Without any arguments, this will open the default profile in a new tab. If an action is not specified, the default profile's equivalent setting will be used.

Command name: newTab

Default bindings:

{ "command": "newTab", "keys": "ctrl+shift+t" },
{ "command": { "action": "newTab", "index": 0 }, "keys": "ctrl+shift+1" },
{ "command": { "action": "newTab", "index": 1 }, "keys": "ctrl+shift+2" },
{ "command": { "action": "newTab", "index": 2 }, "keys": "ctrl+shift+3" },
{ "command": { "action": "newTab", "index": 3 }, "keys": "ctrl+shift+4" },
{ "command": { "action": "newTab", "index": 4 }, "keys": "ctrl+shift+5" },
{ "command": { "action": "newTab", "index": 5 }, "keys": "ctrl+shift+6" },
{ "command": { "action": "newTab", "index": 6 }, "keys": "ctrl+shift+7" },
{ "command": { "action": "newTab", "index": 7 }, "keys": "ctrl+shift+8" },
{ "command": { "action": "newTab", "index": 8 }, "keys": "ctrl+shift+9" }

Actions

Name Necessity Accepts Description
commandline Optional Executable file name as a string Executable run within the tab.
startingDirectory Optional Folder location as a string Directory in which the tab will open.
tabTitle Optional String Title of the new tab.
index Optional Integer Profile that will open based on its position in the dropdown (starting at 0).
profile Optional Profile's name or GUID as a string Profile that will open based on its GUID or name.

Open next tab

This opens the tab to the right of the current one.

Command name: nextTab

Default binding:

{ "command": "nextTab", "keys": "ctrl+tab" }

Open previous tab

This opens the tab to the left of the current one.

Command name: prevTab

Default binding:

{ "command": "prevTab", "keys": "ctrl+shift+tab" }

This opens the tab search box.

Command name: tabSearch

Default binding:

This command is not currently bound in the default settings.

{"command": "tabSearch", "keys": ""}

Windows Terminal tab search

Open a specific tab

This opens a specific tab depending on the index.

Command name: switchToTab

Default bindings:

{ "command": { "action": "switchToTab", "index": 0 }, "keys": "ctrl+alt+1" },
{ "command": { "action": "switchToTab", "index": 1 }, "keys": "ctrl+alt+2" },
{ "command": { "action": "switchToTab", "index": 2 }, "keys": "ctrl+alt+3" },
{ "command": { "action": "switchToTab", "index": 3 }, "keys": "ctrl+alt+4" },
{ "command": { "action": "switchToTab", "index": 4 }, "keys": "ctrl+alt+5" },
{ "command": { "action": "switchToTab", "index": 5 }, "keys": "ctrl+alt+6" },
{ "command": { "action": "switchToTab", "index": 6 }, "keys": "ctrl+alt+7" },
{ "command": { "action": "switchToTab", "index": 7 }, "keys": "ctrl+alt+8" },
{ "command": { "action": "switchToTab", "index": 8 }, "keys": "ctrl+alt+9" }

Actions

Name Necessity Accepts Description
index Required Integer Tab that will open based on its position in the tab bar (starting at 0).

Rename tab

This command can be used to rename a tab to a specific string.

Command name: renameTab

Default binding:

This command is not currently bound in the default settings.

// Rename a tab to "Foo"
{ "command": { "action": "renameTab", "title": "Foo" }, "keys": "" }

// Reset the tab's name
{ "command": { "action": "renameTab", "title": null }, "keys": "" }

Actions

Name Necessity Accepts Description
title Optional String The new title to use for this tab. If omitted, this command will revert the tab title back to its original value.

Open tab rename text box (Preview)

This command changes the tab title into a text field that lets you edit the title for the current tab. Clearing the text field will reset the tab title back to the default for the current shell instance.

Command name: openTabRenamer

Default binding:

This command is not currently bound in the default settings.

{ "command": "openTabRenamer", "keys": "ctrl+alt+a" }

Important

This feature is only available in Windows Terminal Preview.

Change tab color

This command can be used to change the color of a tab to a specific value.

Command name: setTabColor

Default binding:

This command is not currently bound in the default settings.

// Change the tab's color to a bright magenta
{ "command": { "action": "setTabColor", "color": "#ff00ff" }, "keys": "" }

// Reset the tab's color
{ "command": { "action": "setTabColor", "color": null }, "keys": "" }

Actions

Name Necessity Accepts Description
color Optional String, in hex format: "#rgb" or "#rrggbb" The new color to use for this tab. If omitted, this command will revert the tab's color back to its original value.

Open tab color picker

This command can be used to open the color picker for the active tab. The color picker can be used to set a color for the tab at runtime.

Command name: openTabColorPicker

Default binding:

{ "command": "openTabColorPicker" }


Pane management commands

Close pane

This closes the active pane. If there aren't any split panes, this will close the current tab. If there is only one tab open, this will close the window.

Command name: closePane

Default binding:

{ "command": "closePane", "keys": "ctrl+shift+w" }

Move pane focus

This changes focus to a different pane depending on the direction.

Command name: moveFocus

Default bindings:

{ "command": { "action": "moveFocus", "direction": "down" }, "keys": "alt+down" },
{ "command": { "action": "moveFocus", "direction": "left" }, "keys": "alt+left" },
{ "command": { "action": "moveFocus", "direction": "right" }, "keys": "alt+right" },
{ "command": { "action": "moveFocus", "direction": "up" }, "keys": "alt+up" }

Actions

Name Necessity Accepts Description
direction Required "left", "right", "up", "down" Direction in which the focus will move.

Zoom a pane (Preview)

This expands the focused pane to fill the entire contents of the window.

Command name: togglePaneZoom

Default binding:

{ "command": "togglePaneZoom" }

Windows Terminal toggle pane zoom

Important

This feature is only available in Windows Terminal Preview.

Resize a pane

This changes the size of the active pane.

Command name: resizePane

Default bindings:

{ "command": { "action": "resizePane", "direction": "down" }, "keys": "alt+shift+down" },
{ "command": { "action": "resizePane", "direction": "left" }, "keys": "alt+shift+left" },
{ "command": { "action": "resizePane", "direction": "right" }, "keys": "alt+shift+right" },
{ "command": { "action": "resizePane", "direction": "up" }, "keys": "alt+shift+up" }

Actions

Name Necessity Accepts Description
direction Required "left", "right", "up", "down" Direction in which the pane will be resized.

Split a pane

This halves the size of the active pane and opens another. Without any arguments, this will open the default profile in the new pane. If an action is not specified, the default profile's equivalent setting will be used.

Command name: splitPane

Default bindings:

// In settings.json
{ "command": { "action": "splitPane", "split": "auto", "splitMode": "duplicate" }, "keys": "alt+shift+d" },

// In defaults.json
{ "command": { "action": "splitPane", "split": "horizontal"}, "keys": "alt+shift+-" },
{ "command": { "action": "splitPane", "split": "vertical"}, "keys": "alt+shift+plus" }

Actions

Name Necessity Accepts Description
split Required "vertical", "horizontal", "auto" How the pane will split. "auto" will split in the direction that provides the most surface area.
commandline Optional Executable file name as a string Executable run within the pane.
startingDirectory Optional Folder location as a string Directory in which the pane will open.
tabTitle Optional String Title of the tab when the new pane is focused.
index Optional Integer Profile that will open based on its position in the dropdown (starting at 0).
profile Optional Profile's name or GUID as a string Profile that will open based on its GUID or name.
splitMode Optional "duplicate" Controls how the pane splits. Only accepts "duplicate", which will duplicate the focused pane's profile into a new pane.


Clipboard integration commands

Copy

This copies the selected terminal content to your clipboard.

Command name: copy

Default bindings:

// In settings.json
{ "command": { "action": "copy", "singleLine": false }, "keys": "ctrl+c" },

// In defaults.json
{ "command": { "action": "copy", "singleLine": false }, "keys": "ctrl+shift+c" },
{ "command": { "action": "copy", "singleLine": false }, "keys": "ctrl+insert" }

Actions

Name Necessity Accepts Description
singleLine Optional true, false When true, the copied content will be copied as a single line. When false, newlines persist from the selected text.
copyFormatting Optional true, false, "all", "none", "html", "rtf" When true, the color and font formatting of the selected text is also copied to your clipboard. When false, only plain text is copied to your clipboard. You can also specify which formats you would like to copy. When null, the global "copyFormatting" behavior is inherited.

Paste

This inserts the content that was copied onto the clipboard.

Command name: paste

Default bindings:

// In settings.json
{ "command": "paste", "keys": "ctrl+v" },

// In defaults.json
{ "command": "paste", "keys": "ctrl+shift+v" },
{ "command": "paste", "keys": "shift+insert" }


Scrollback commands

Scroll up

This scrolls the screen up by the number of rows defined by "rowsToScroll". If "rowsToScroll" is not provided, it will scroll up the amount defined by the system default, which is the same amount as mouse scrolling.

Command name: scrollUp

Default binding:

{ "command": "scrollUp", "keys": "ctrl+shift+up" }

Actions

Name Necessity Accepts Description
rowsToScroll Optional Integer The number of rows to scroll.

Important

The "rowsToScroll" action is only available in Windows Terminal Preview.

Scroll down

This scrolls the screen down by the number of rows defined by "rowsToScroll". If "rowsToScroll" is not provided, it will scroll down the amount defined by the system default, which is the same amount as mouse scrolling.

Command name: scrollDown

Default binding:

{ "command": "scrollDown", "keys": "ctrl+shift+down" }

Actions

Name Necessity Accepts Description
rowsToScroll Optional Integer The number of rows to scroll.

Important

The "rowsToScroll" action is only available in Windows Terminal Preview.

Scroll up a whole page

This scrolls the screen up by a whole page, which is the height of the window.

Command name: scrollUpPage

Default binding:

{ "command": "scrollUpPage", "keys": "ctrl+shift+pgup" }

Scroll down a whole page

This scrolls the screen down by a whole page, which is the height of the window.

Command name: scrollDownPage

Default binding:

{ "command": "scrollDownPage", "keys": "ctrl+shift+pgdn" }


Visual adjustment commands

Adjust font size

This changes the text size by a specified point amount.

Command name: adjustFontSize

Default bindings:

{ "command": { "action": "adjustFontSize", "delta": 1 }, "keys": "ctrl+=" },
{ "command": { "action": "adjustFontSize", "delta": -1 }, "keys": "ctrl+-" }

Actions

Name Necessity Accepts Description
delta Required Integer Amount of size change per command invocation.

Reset font size

This resets the text size to the default value.

Command name: resetFontSize

Default binding:

{ "command": "resetFontSize", "keys": "ctrl+0" }

Toggle retro terminal effects

This toggles the "retro terminal effect", which is enabled with the profile setting experimental.retroTerminalEffect.

Command name: toggleRetroEffect

Default binding:

{ "command": "toggleRetroEffect" }

Set the color scheme

Changes the active color scheme.

Command name: setColorScheme

Actions

Name Necessity Accepts Description
colorScheme Required String The name of the color scheme to apply.

Example binding:

{ "command": { "action": "setColorScheme", "colorScheme": "Campbell" }, "keys": "" }


Unbind keys

This unbinds the associated keys from any command.

Command name: unbound