# Windows Terminal — User Guide

Windows Terminal is Microsoft's modern, GPU-accelerated terminal application for Windows 10 and 11. It consolidates Command Prompt, PowerShell, WSL distributions, Azure Cloud Shell, and any command-line application into a single window with multiple tabs, split panes, Unicode/UTF-8 support, custom themes, and rich text rendering with a DirectX-based rendering engine. The project is open source under the MIT license.

This guide covers everything you need to install, configure, and use Windows Terminal effectively. For architecture internals, security hardening, and deep configuration reference, see the Admin Guide.

## 1. Quick Start

### What You Get

Windows Terminal gives you a unified command-line experience across all your shells:

- **Tabs and panes** -- run multiple shells side by side in a single window
- **GPU-accelerated rendering** -- smooth scrolling and crisp text via DirectX
- **Full Unicode and UTF-8** -- emoji, CJK characters, and complex scripts render correctly
- **Custom themes and color schemes** -- dark, light, and fully customizable appearances
- **Automatic shell profiles** -- detects installed shells (PowerShell, WSL, Azure Cloud Shell, Visual Studio Developer shells)
- **Keyboard shortcuts** -- extensive default bindings with full customization
- **Quake mode** -- a drop-down terminal that appears with a global hotkey
- **Command palette** -- search and execute any action by name
- **Shell integration and suggestions** -- command history, marks on the scrollbar, and intelligent suggestions

> [!TIP]
> The fastest way to get started: install from the Microsoft Store, launch Windows Terminal, and press `Ctrl+Shift+T` to open a new tab or `Alt+Shift+Plus` to split the current pane vertically.

### Prerequisites

- Windows 10 version 1903 (build 18362) or later, or Windows 11
- x64 or ARM64 processor

### Install in 30 Seconds

```powershell
winget install --id Microsoft.WindowsTerminal -e
```

Or open the Microsoft Store and search for "Windows Terminal."

### Your First 60 Seconds

1. Launch Windows Terminal from the Start menu or by running `wt` in any shell.
2. The default profile (typically Windows PowerShell) opens automatically.
3. Press `Ctrl+Shift+T` to open a new tab with the default profile.
4. Press `Alt+Shift+Plus` to split the current pane vertically, or `Alt+Shift+Minus` to split horizontally.
5. Navigate between panes with `Alt+Arrow` keys.
6. Press `Ctrl+Shift+P` to open the Command Palette and explore available actions.
7. Press `Ctrl+,` to open the Settings UI and start customizing.

### What to Try Next

- Configure a background image or acrylic transparency (see Configuration, Profile Settings)
- Set up quake mode for instant terminal access (see Common Tasks)
- Create custom keybindings (see Common Tasks, Custom Keybindings)
- Explore the full action list to discover capabilities (see Core Usage, Actions Reference)

---

## 2. Installation

### System Requirements

| Requirement | Minimum |
|---|---|
| Operating System | Windows 10 version 1903 (build 18362) or later |
| Architecture | x64, ARM64 |
| Disk Space | ~80 MB |
| .NET Runtime | Not required (self-contained) |
| GPU | Any DirectX 10.1 capable GPU (software fallback available) |

> [!IMPORTANT]
> Windows Terminal requires the Windows 10 1903 update or newer. If you are on an older build, the application will not install. Check your version by running `winver` from the Run dialog.

### Installation Methods

#### Microsoft Store (Recommended)

The Store provides automatic updates and is the simplest method:

1. Open the Microsoft Store application.
2. Search for "Windows Terminal."
3. Click **Get** or **Install**.
4. Once installed, launch from the Start menu or by typing `wt` in any shell.

#### winget

```powershell
winget install --id Microsoft.WindowsTerminal -e
```

For the Preview build:

```powershell
winget install --id Microsoft.WindowsTerminal.Preview -e
```

#### Chocolatey

```powershell
choco install microsoft-windows-terminal
```

#### Scoop

```powershell
scoop bucket add extras
scoop install windows-terminal
```

#### GitHub Releases (Manual)

1. Go to the [Releases page](https://github.com/microsoft/terminal/releases) on GitHub.
2. Download the `.msixbundle` file for the desired version.
3. Double-click the bundle to install, or use PowerShell:

```powershell
Add-AppxPackage -Path .\Microsoft.WindowsTerminal_<version>.msixbundle
```

> [!WARNING]
> Manual installs from GitHub do not auto-update. You must check for and install new releases yourself. The Microsoft Store or winget methods are strongly preferred for staying current with security patches and bug fixes.

#### Preview Version

Windows Terminal Preview is a separate installation that receives new features before the stable release. Both the stable and preview versions can be installed side by side:

```powershell
winget install --id Microsoft.WindowsTerminal.Preview -e
```

### Verify Installation

```powershell
wt --version
```

This prints the installed version. If the command is not found, ensure the installation completed and your PATH includes the Windows Apps directory.

### Post-Install Verification

After installation, confirm that Windows Terminal is working:

1. Open the Start menu and type "Terminal" or "Windows Terminal."
2. The application should launch with your default shell profile.
3. Check the dropdown (the `+` button or the downward arrow next to it) to see detected profiles.
4. Press `Ctrl+,` to open Settings and verify the Settings UI loads.

### Setting as Default Terminal (Windows 11)

On Windows 11, you can set Windows Terminal as the default terminal application for all console applications:

1. Open **Settings > Privacy & security > For developers** (or open Windows Terminal Settings).
2. Under **Terminal**, select **Windows Terminal**.
3. Alternatively, in Windows Terminal Settings, go to **Startup** and set **Default terminal application** to **Windows Terminal**.

### Install Troubleshooting

**"This app package is not supported for installation" error**
You are likely on an unsupported Windows version. Run `winver` and confirm you are on build 18362 or later.

**Store install hangs or fails**
Try `wsreset.exe` to reset the Store cache, then retry. If that fails, use the winget method instead.

**winget command not found**
Install the "App Installer" package from the Microsoft Store, which provides winget.

**`wt` command not recognized after install**
Restart your shell session. If still not found, the install may not have created the app alias. Check Settings > Apps > App execution aliases and ensure "Windows Terminal" is enabled.

**"Windows cannot install package" with .msixbundle**
Ensure Developer Mode is enabled (Settings > Privacy & security > For developers) or that sideloading is allowed on your device.

**Uninstall and reinstall**
If the installation is corrupted, remove it first:
```powershell
Get-AppxPackage Microsoft.WindowsTerminal | Remove-AppxPackage
```
Then reinstall using your preferred method.

---

## 3. Configuration

Windows Terminal stores its configuration in a JSON file called `settings.json`. You can edit this file directly for full control, or use the built-in Settings UI for a graphical experience.

### Settings File Location

| Install Method | Path |
|---|---|
| Microsoft Store / winget | `%LOCALAPPDATA%\Packages\Microsoft.WindowsTerminal_8wekyb3d8bbwe\LocalState\settings.json` |
| Unpackaged / Scoop | `%LOCALAPPDATA%\Microsoft\Windows Terminal\settings.json` |

Open the settings file directly by pressing `Ctrl+Shift+,` (this opens the JSON file in your default editor), or open the Settings UI with `Ctrl+,`.

> [!TIP]
> The `settings.json` file is validated against a JSON schema. Most editors (VS Code, for example) provide autocompletion and validation when the `$schema` property is present at the top of the file. If it is missing, add: `"$schema": "https://aka.ms/terminal-profiles-schema"`

### Settings File Structure

The top-level structure of `settings.json`:

```json
{
    "$schema": "https://aka.ms/terminal-profiles-schema",
    "defaultProfile": "{GUID-of-your-preferred-profile}",
    "profiles": {
        "defaults": {
            // Settings applied to ALL profiles
        },
        "list": [
            // Individual profile definitions
        ]
    },
    "schemes": [
        // Color scheme definitions
    ],
    "actions": [
        // Custom actions and keybindings
    ],
    "keybindings": [
        // Keychord-to-action-ID bindings
    ],
    "themes": [
        // Custom theme definitions
    ]
}
```

### Global Settings

These properties control the entire application window, independent of any specific profile.

| Setting | Type | Default | Description |
|---|---|---|---|
| `defaultProfile` | string | (required) | GUID or name of the profile opened by default when creating a new tab |
| `theme` | string | `"dark"` | Application theme. Built-in values: `"dark"`, `"light"`, `"system"`, or a custom theme name. Also accepts a `{"dark": "...", "light": "..."}` object to auto-switch |
| `launchMode` | string | `"default"` | Window launch mode. Values: `"default"`, `"maximized"`, `"fullscreen"`, `"focus"`, `"maximizedFocus"` |
| `initialCols` | integer | `120` | Number of columns at launch (ignored when `launchMode` is `"maximized"` or `"fullscreen"`) |
| `initialRows` | integer | `30` | Number of rows at launch (ignored when `launchMode` is `"maximized"` or `"fullscreen"`) |
| `copyOnSelect` | boolean | `false` | When `true`, text is copied to the clipboard as soon as it is selected |
| `copyFormatting` | boolean/string/array | `true` | When `true`, copies color and font formatting along with text. Set to `false` for plain text. Can also be an array: `["html", "rtf"]` |
| `trimPaste` | boolean | `true` | Automatically trims trailing whitespace when pasting |
| `trimBlockSelection` | boolean | `true` | Removes trailing whitespace from rectangular (block) selections when copying |
| `tabWidthMode` | string | `"equal"` | Tab sizing. `"equal"` makes all tabs the same width, `"titleLength"` sizes to title text, `"compact"` shrinks unfocused tabs to icon-only |
| `showTabsInTitlebar` | boolean | `true` | When `true`, tabs are rendered in the title bar area |
| `showTerminalTitleInTitlebar` | boolean | `true` | When `true`, the title bar shows the selected tab's title |
| `wordDelimiters` | string | ` ./\()\"'-:,.;<>~!@#$%^&*\|+=[]{}~?\│` | Characters used as word boundaries for double-click selection |
| `startupActions` | string | (none) | A `wt` command-line string executed at startup (e.g., `"new-tab -p PowerShell ; split-pane -p Ubuntu"`) |
| `alwaysOnTop` | boolean | `false` | Keeps the window above all other windows |
| `focusFollowMouse` | boolean | `false` | When `true`, panes receive focus on mouse hover |
| `minimizeToNotificationArea` | boolean | `false` | Minimizing sends the window to the system tray instead of the taskbar |
| `alwaysShowNotificationIcon` | boolean | `false` | Always show the Terminal icon in the notification area |
| `snapToGridOnResize` | boolean | `false` | Snap window edges to character cell boundaries |
| `centerOnLaunch` | boolean | `false` | Center the window on the display at launch |
| `firstWindowPreference` | string | `"defaultProfile"` | `"persistedWindowLayout"` restores the previous window layout on launch |
| `windowingBehavior` | string | `"useNew"` | Controls how new instances attach. `"useExisting"` opens a tab in the last-used window; `"useAnyExisting"` does so across all desktops |
| `tabSwitcherMode` | string | `"inOrder"` | Tab switcher ordering. `"mru"` for most-recently-used, `"inOrder"` for left-to-right, `"disabled"` to turn it off |
| `newTabPosition` | string | `"afterLastTab"` | Where new tabs appear. Also accepts `"afterCurrentTab"` |
| `autoHideWindow` | boolean | `false` | Hide the window as soon as it loses focus |
| `showAdminShield` | boolean | `true` | Show a shield icon in the tab row when running as administrator |
| `useAcrylicInTabRow` | boolean | `false` | Apply acrylic material to the tab row |
| `disableAnimations` | boolean | `false` | Disable visual animations throughout the application |
| `language` | string/null | `null` | Override the application language with a BCP-47 tag (e.g., `"en-US"`) |

**Warning and compatibility settings:**

| Setting | Type | Default | Description |
|---|---|---|---|
| `warning.confirmCloseAllTabs` | boolean | `true` | Show confirmation when closing a window with multiple tabs |
| `warning.largePaste` | boolean | `true` | Warn before pasting text larger than 5 KiB |
| `warning.multiLinePaste` | boolean | `true` | Warn before pasting text containing newlines |
| `warning.inputService` | boolean | `true` | Warn if the Touch Keyboard and Handwriting Panel Service is disabled |
| `compatibility.allowHeadless` | boolean | `false` | Allow Terminal to run in the background with no visible windows (required for `globalSummon`/`quakeMode` to work after all windows are closed) |
| `compatibility.textMeasurement` | string | `"graphemes"` | How text is grouped into cells: `"graphemes"` (modern Unicode), `"wcswidth"` (UNIX-style), or `"console"` (legacy Windows) |
| `compatibility.ambiguousWidth` | string | `"narrow"` | Cell width for East Asian ambiguous characters: `"narrow"` or `"wide"` |

**Rendering settings:**

| Setting | Type | Default | Description |
|---|---|---|---|
| `rendering.graphicsAPI` | string | `"automatic"` | `"automatic"`, `"direct2d"`, or `"direct3d11"`. Direct3D 11 is more performant; Direct2D is more stable |
| `rendering.disablePartialInvalidation` | boolean | (unset) | Switch from FLIP_SEQUENTIAL to FLIP_DISCARD swap chain |
| `rendering.software` | boolean | (unset) | Force software rasterization (WARP). Leave disabled unless debugging |

**Experimental settings:**

| Setting | Type | Default | Description |
|---|---|---|---|
| `experimental.detectURLs` | boolean | `true` | Detect and underline clickable URLs (Ctrl+click to open) |
| `experimental.enableColorSelection` | boolean | `false` | Add legacy-style color selection keybindings |
| `experimental.useBackgroundImageForWindow` | boolean | `false` | Expand the focused profile's background image behind all panes |
| `experimental.scrollToZoom` | boolean | `true` | Ctrl+scroll to increase/decrease font size |
| `experimental.scrollToChangeOpacity` | boolean | `true` | Ctrl+Shift+scroll to change window opacity |
| `compatibility.enableUnfocusedAcrylic` | boolean | `true` | Allow acrylic in unfocused windows |

### Profile Settings

Profile settings control the behavior and appearance of individual shell sessions. Settings placed under `profiles.defaults` apply to all profiles and can be overridden per-profile in the `profiles.list` array.

#### Identity and Shell

| Setting | Type | Default | Description |
|---|---|---|---|
| `name` | string | (required) | Display name for the profile in menus and tabs |
| `guid` | string | (required) | Unique GUID in registry format: `"{00000000-0000-0000-0000-000000000000}"` |
| `commandline` | string | (varies) | Executable to run (e.g., `"powershell.exe"`, `"wsl.exe -d Ubuntu"`, `"cmd.exe"`) |
| `startingDirectory` | string/null | (varies) | Directory the shell starts in (e.g., `"C:\\Users\\me"` or `"%USERPROFILE%"`) |
| `icon` | string/null | (varies) | Path to an image file or an emoji used as the profile icon |
| `hidden` | boolean | `false` | When `true`, the profile does not appear in the dropdown or new tab menu |
| `source` | string/null | (none) | The dynamic profile generator that created this profile (e.g., `"Windows.Terminal.Wsl"`) |
| `elevate` | boolean | `false` | When `true`, the profile always opens in an elevated (administrator) context |

#### Appearance

| Setting | Type | Default | Description |
|---|---|---|---|
| `colorScheme` | string/object | `"Campbell"` | Color scheme name, or `{"dark": "...", "light": "..."}` object for automatic light/dark switching |
| `font.face` | string | `"Cascadia Mono"` | Font family name |
| `font.size` | number | `12` | Font size in points (minimum 1) |
| `font.weight` | string/integer | `"normal"` | Font weight. Named values: `"thin"`, `"extra-light"`, `"light"`, `"semi-light"`, `"normal"`, `"medium"`, `"semi-bold"`, `"bold"`, `"extra-bold"`, `"black"`, `"extra-black"`. Or numeric 100-990 |
| `font.features` | object | (none) | OpenType font features as key-value pairs (e.g., `{"ss01": 1, "liga": 0}`) |
| `font.axes` | object | (none) | Variable font axes as key-value pairs (e.g., `{"wght": 200}`) |
| `font.cellWidth` | string/null | (none) | Override cell width (CSS-like: `"10px"`, `"1ch"`, `"110%"`) |
| `font.cellHeight` | string/null | (none) | Override cell height (CSS-like: `"1.2"`, `"14pt"`) |
| `cursorShape` | string | `"bar"` | Cursor style: `"bar"`, `"doubleUnderscore"`, `"emptyBox"`, `"filledBox"`, `"underscore"`, `"vintage"` |
| `cursorHeight` | integer/null | `25` | Height of the vintage cursor as a percentage (1-100). Only applies when `cursorShape` is `"vintage"` |
| `cursorColor` | string/null | (from scheme) | Override cursor color in `#rrggbb` format |
| `foreground` | string/null | `"#cccccc"` | Override text color in `#rrggbb` format |
| `background` | string/null | `"#0c0c0c"` | Override background color in `#rrggbb` format |
| `selectionBackground` | string/null | (from scheme) | Override selection background color |
| `opacity` | number | `100` | Window opacity (0-100). Defaults to 50 when `useAcrylic` is `true` |
| `useAcrylic` | boolean | `false` | Enable acrylic (translucent) material background |
| `backgroundImage` | string/null | (none) | Path to a background image file, or `"desktopWallpaper"` to use your desktop wallpaper |
| `backgroundImageOpacity` | number | `1.0` | Background image transparency (0.0 to 1.0) |
| `backgroundImageStretchMode` | string | `"uniformToFill"` | How the image fills the pane: `"fill"`, `"none"`, `"uniform"`, `"uniformToFill"` |
| `backgroundImageAlignment` | string | `"center"` | Image alignment: `"center"`, `"left"`, `"right"`, `"top"`, `"bottom"`, `"topLeft"`, `"topRight"`, `"bottomLeft"`, `"bottomRight"` |
| `intenseTextStyle` | string | `"bright"` | How bold/intense text is rendered: `"none"`, `"bold"`, `"bright"`, `"all"` |
| `adjustIndistinguishableColors` | string | `"never"` | Adjust foreground colors for visibility: `"never"`, `"indexed"` (only scheme colors), `"always"` |
| `antialiasingMode` | string | `"grayscale"` | Text antialiasing: `"grayscale"`, `"cleartype"`, `"aliased"` |

#### Behavior

| Setting | Type | Default | Description |
|---|---|---|---|
| `historySize` | integer | `9001` | Number of scrollback lines (-1 for unlimited) |
| `padding` | string/integer | `"8, 8, 8, 8"` | Padding around the text area. Formats: `"8"` (all sides), `"8, 4"` (left-right, top-bottom), `"8, 4, 8, 4"` (left, top, right, bottom) |
| `scrollbarState` | string | `"visible"` | Scrollbar visibility: `"visible"`, `"hidden"`, `"always"` |
| `closeOnExit` | string | `"automatic"` | Profile close behavior: `"automatic"`, `"graceful"`, `"always"`, `"never"` |
| `bellStyle` | string/boolean/array | `"audible"` | Bell behavior: `"audible"`, `"window"`, `"taskbar"`, `"all"`, `"none"`, or an array like `["audible", "taskbar"]` |
| `bellSound` | string/array/null | (none) | Custom sound file path for the bell. Accepts an array for random selection |
| `snapOnInput` | boolean | `true` | Scroll to the input line when typing |
| `altGrAliasing` | boolean | `true` | Treat Ctrl+Alt as AltGr (important for international keyboards) |
| `suppressApplicationTitle` | boolean | `false` | When `true`, prevent the shell from changing the tab title |
| `tabTitle` | string/null | (none) | Override the initial tab title |
| `tabColor` | string/null | (none) | Set a persistent tab color in `#rrggbb` format |
| `pathTranslationStyle` | string | `"none"` | Transform dragged-and-dropped file paths: `"none"`, `"wsl"`, `"cygwin"`, `"msys2"`, `"mingw"` |
| `dragDropDelimiter` | string | `" "` | Delimiter between multiple dropped files |
| `autoMarkPrompts` | boolean | `true` | Automatically mark command prompts (requires shell integration) |
| `showMarksOnScrollbar` | boolean | `false` | Display marks on the scrollbar |
| `environment` | object | (none) | Additional environment variables as key-value pairs |

**Unfocused appearance:** Set `unfocusedAppearance` to an object with appearance properties (`colorScheme`, `cursorShape`, `opacity`, `backgroundImage`, etc.) to customize how a pane looks when it is not focused.

#### Experimental Profile Settings

| Setting | Type | Default | Description |
|---|---|---|---|
| `experimental.retroTerminalEffect` | boolean | (unset) | Enable CRT-style scanline and glow effects |
| `experimental.pixelShaderPath` | string | (none) | Path to a custom HLSL pixel shader file. Overrides `retroTerminalEffect` |
| `experimental.rightClickContextMenu` | boolean | `false` | Right-click shows a context menu instead of pasting |
| `experimental.repositionCursorWithMouse` | boolean | `false` | Click to reposition the text cursor on the current command line |
| `experimental.rainbowSuggestions` | boolean | `false` | Render command suggestions in rainbow colors |
| `compatibility.reloadEnvironmentVariables` | boolean | `true` | Reload environment variables when opening new tabs/panes |
| `compatibility.input.forceVT` | boolean | `false` | Force legacy VT input encoding |
| `compatibility.allowDECRQCRA` | boolean | `false` | Support DECRQCRA escape sequence |
| `compatibility.allowOSC52` | boolean | `true` | Allow applications to set clipboard contents via OSC 52 |
| `answerbackMessage` | string/null | (none) | Response sent when an ENQ control character is received |

### Color Schemes

Color schemes define the 16 ANSI colors plus foreground, background, cursor, and selection colors. Each scheme is an object in the `schemes` array.

```json
{
    "name": "My Custom Scheme",
    "foreground": "#D4D4D4",
    "background": "#1E1E1E",
    "cursorColor": "#FFFFFF",
    "selectionBackground": "#264F78",
    "black": "#000000",
    "red": "#CD3131",
    "green": "#0DBC79",
    "yellow": "#E5E510",
    "blue": "#2472C8",
    "purple": "#BC3FBC",
    "cyan": "#11A8CD",
    "white": "#E5E5E5",
    "brightBlack": "#666666",
    "brightRed": "#F14C4C",
    "brightGreen": "#23D18B",
    "brightYellow": "#F5F543",
    "brightBlue": "#3B8EEA",
    "brightCyan": "#29B8DB",
    "brightPurple": "#D670D6",
    "brightWhite": "#E5E5E5"
}
```

**Built-in schemes:** Campbell (default), Campbell Powershell, One Half Dark, One Half Light, Solarized Dark, Solarized Light, Tango Dark, Tango Light, Vintage.

Profiles can also use light/dark scheme switching:

```json
"colorScheme": {
    "dark": "One Half Dark",
    "light": "One Half Light"
}
```

### Themes

Themes control the non-terminal UI chrome: the title bar, tab row, and window frame. They are defined in the top-level `themes` array and referenced by the global `theme` property.

```json
{
    "name": "My Theme",
    "tab": {
        "background": "#1E1E1E",
        "unfocusedBackground": "#2D2D2D",
        "showCloseButton": "hover",
        "iconStyle": "default"
    },
    "tabRow": {
        "background": "#1E1E1E",
        "unfocusedBackground": "#2D2D2D"
    },
    "window": {
        "applicationTheme": "dark",
        "useMica": false,
        "frame": "accent",
        "unfocusedFrame": "#444444"
    }
}
```

Theme color values can be `#rrggbb`, `#rrggbbaa`, `"accent"` (the OS accent color), `"terminalBackground"` (the active pane's background), or `null`.

The `showCloseButton` property accepts: `"always"`, `"hover"`, `"never"`, `"activeOnly"`.

The `iconStyle` property accepts: `"default"`, `"hidden"`, `"monochrome"`.

On Windows 11, the `frame` and `unfocusedFrame` properties colorize the window border. The `experimental.rainbowFrame` property (boolean, default `false`) overrides these to cycle through all colors.

The `useMica` property enables the Windows 11 Mica material behind the entire window.

> [!NOTE]
> The theme names `"dark"`, `"light"`, and `"system"` are reserved and cannot be used for custom themes. Use any other name.

---

## 4. Core Usage

### Tabs

Tabs let you run multiple shell sessions in a single window.

| Action | Default Keybinding |
|---|---|
| New tab (default profile) | `Ctrl+Shift+T` |
| New tab (profile by index 1-9) | `Ctrl+Shift+1` through `Ctrl+Shift+9` |
| Close current tab | `Ctrl+Shift+W` |
| Next tab | `Ctrl+Tab` |
| Previous tab | `Ctrl+Shift+Tab` |
| Switch to tab by index | `Ctrl+Alt+1` through `Ctrl+Alt+9` |
| Duplicate tab | (unbound by default -- assign via `duplicateTab` action) |
| Move tab forward | (unbound -- assign via `moveTab` action with `"direction": "forward"`) |
| Move tab backward | (unbound -- assign via `moveTab` action with `"direction": "backward"`) |
| Restore last closed tab/pane | (unbound -- assign via `restoreLastClosed` action) |
| Tab search | (unbound -- assign via `tabSearch` action) |
| Rename tab | Right-click the tab, then select "Rename Tab," or use the `openTabRenamer` action |
| Close other tabs | Right-click a tab and select "Close Other Tabs," or use the `closeOtherTabs` action |
| Close tabs to the right | Right-click a tab and select "Close Tabs to the Right," or use the `closeTabsAfter` action |

> [!TIP]
> You can set a custom color for any tab by right-clicking it and selecting "Color..." or by using the `openTabColorPicker` action. To set a permanent color per profile, add `"tabColor": "#hexcolor"` to the profile definition.

### Panes

Panes split a tab into multiple views, each running its own shell session.

| Action | Default Keybinding |
|---|---|
| Split vertically (side by side) | `Alt+Shift+Plus` |
| Split horizontally (top/bottom) | `Alt+Shift+Minus` |
| Auto-split (based on available space) | (default for `splitPane` with `"split": "auto"`) |
| Navigate to pane (directional) | `Alt+Left`, `Alt+Right`, `Alt+Up`, `Alt+Down` |
| Resize pane | `Alt+Shift+Left`, `Alt+Shift+Right`, `Alt+Shift+Up`, `Alt+Shift+Down` |
| Close pane | `Ctrl+Shift+W` |
| Toggle pane zoom | (unbound -- assign via `togglePaneZoom` action) |
| Swap pane | (unbound -- assign via `swapPane` action) |
| Move pane to another tab | (unbound -- assign via `movePane` action) |
| Close other panes | (unbound -- assign via `closeOtherPanes` action) |
| Toggle split orientation | (unbound -- assign via `toggleSplitOrientation` action) |

You can split with a specific profile:

```json
{
    "command": {
        "action": "splitPane",
        "split": "right",
        "profile": "Ubuntu"
    },
    "keys": "ctrl+alt+u"
}
```

The `size` parameter (0.0 to 1.0) controls the new pane's proportion of the available space. The default is `0.5` (equal split).

> [!NOTE]
> The `moveFocus` action supports directions beyond the four cardinals: `"previous"` goes to the most recently focused pane, `"nextInOrder"` and `"previousInOrder"` traverse panes sequentially, `"first"` focuses the first pane, and `"parent"` / `"child"` navigate the pane tree hierarchy.

### Command Palette

The Command Palette provides searchable access to every action in Windows Terminal.

- **Open in action mode:** `Ctrl+Shift+P` -- search and execute actions by name
- **Open in command-line mode:** Assign a keybinding with `"launchMode": "commandLine"` to type `wt` subcommands directly

```json
{
    "command": {
        "action": "commandPalette",
        "launchMode": "commandLine"
    },
    "keys": "ctrl+shift+enter"
}
```

### Search

Search within the terminal scrollback buffer:

| Action | Default Keybinding |
|---|---|
| Open search box | `Ctrl+Shift+F` |
| Find next match | (assign via `findMatch` with `"direction": "next"`) |
| Find previous match | (assign via `findMatch` with `"direction": "prev"`) |

### Copy and Paste

| Action | Default Keybinding |
|---|---|
| Copy | `Ctrl+Shift+C` (or `Ctrl+C` when text is selected) |
| Paste | `Ctrl+Shift+V` (or `Ctrl+V`) |

Copy supports several formatting options as action arguments:

- `singleLine` (boolean, default `false`) -- collapse all lines into one
- `copyFormatting` (boolean/string/array) -- include color/font formatting as HTML and/or RTF
- `dismissSelection` (boolean, default `true`) -- clear the selection after copying
- `withControlSequences` (boolean, default `false`) -- include raw ANSI escape sequences

### Scrollback

| Action | Default Keybinding |
|---|---|
| Scroll up (one line) | `Ctrl+Shift+Up` |
| Scroll down (one line) | `Ctrl+Shift+Down` |
| Scroll up (one page) | `Ctrl+Shift+PageUp` |
| Scroll down (one page) | `Ctrl+Shift+PageDown` |
| Scroll to top | (unbound -- assign via `scrollToTop`) |
| Scroll to bottom | (unbound -- assign via `scrollToBottom`) |
| Scroll to previous mark | (unbound -- assign via `scrollToMark` with `"direction": "previous"`) |
| Scroll to next mark | (unbound -- assign via `scrollToMark` with `"direction": "next"`) |
| Scroll to first mark | (unbound -- assign via `scrollToMark` with `"direction": "first"`) |
| Scroll to last mark | (unbound -- assign via `scrollToMark` with `"direction": "last"`) |

The `scrollUp` and `scrollDown` actions accept a `rowsToScroll` parameter to scroll a specific number of lines.

### Window Modes

| Mode | How to Activate |
|---|---|
| Fullscreen | `Alt+Enter` or `F11`, or the `toggleFullscreen` action |
| Focus mode (hides tabs and title bar) | `toggleFocusMode` action |
| Always on top | `toggleAlwaysOnTop` action |
| Quake mode (dropdown window) | `Win+`` ` (backtick), or the `quakeMode` action |
| Maximized | `setMaximized` action |
| Read-only mode | `toggleReadOnlyMode` action -- prevents keyboard input to the pane |

> [!IMPORTANT]
> Quake mode summons a special window named `_quake` that drops down from the top of the screen. To make it work even when Terminal has no open windows, set `"compatibility.allowHeadless": true` in your global settings. Without this, quake mode only works while Terminal is already running.

### Suggestions

The suggestions UI displays command history, tasks, and other sources as a filterable overlay:

```json
{
    "command": {
        "action": "showSuggestions",
        "source": "all",
        "useCommandline": true
    },
    "keys": "ctrl+space"
}
```

The `source` parameter accepts `"commandHistory"`, `"tasks"`, `"all"`, or an array of sources. When `useCommandline` is `true`, the current partially-typed command prepopulates the filter (requires shell integration).

### Tasks and Snippets

Windows Terminal supports `.wt.json` files in your project directories. These files define named command snippets that appear in the suggestions UI when you are working in that directory:

```json
{
    "$version": "1.0.0",
    "snippets": [
        {
            "input": "npm run build\r",
            "name": "Build project",
            "description": "Run the build script"
        }
    ]
}
```

### Mark Mode and Selection

- **Enter mark mode:** Assign the `markMode` action. In mark mode, arrow keys move the cursor to create a selection without holding the mouse.
- **Expand selection to word:** `expandSelectionToWord` action
- **Toggle block selection:** `toggleBlockSelection` action
- **Switch selection endpoint:** `switchSelectionEndpoint` action
- **Select all:** `selectAll` action

### URL Detection and Web Search

When `experimental.detectURLs` is `true` (the default), URLs in terminal output are underlined on hover and can be opened with `Ctrl+Click`.

The `searchWeb` action opens a browser with selected text as the query:

```json
{
    "command": {
        "action": "searchWeb",
        "queryUrl": "https://www.google.com/search?q=%s"
    },
    "keys": "ctrl+shift+s"
}
```

The `%s` placeholder is replaced with the selected text.

### Visual Customization

**Opacity adjustment at runtime:** Use the `adjustOpacity` action to change window transparency on the fly. With `"relative": true`, the `opacity` parameter is additive (e.g., `+10` or `-10`).

**Retro terminal effect:** Set `"experimental.retroTerminalEffect": true` in a profile for a CRT-style appearance with scanlines and phosphor glow.

**Custom pixel shaders:** Set `"experimental.pixelShaderPath"` to the path of an HLSL file. The `samples/PixelShaders/` directory in the Windows Terminal repository contains example shaders. This overrides the retro terminal effect.

**Background images:** Set `backgroundImage`, `backgroundImageOpacity`, `backgroundImageStretchMode`, and `backgroundImageAlignment` in a profile. Use the special value `"desktopWallpaper"` to mirror your desktop wallpaper.

**Shader effects toggle:** The `toggleShaderEffects` action enables/disables the pixel shader or retro effect at runtime.

### Actions Reference

The following table documents every action available in Windows Terminal. Use these in the `actions` array of `settings.json` or bind them via the `keybindings` array.

| Action | Description | Key Arguments |
|---|---|---|
| `addMark` | Add a scroll mark at the current position | `color` (optional, `#rrggbb`) |
| `adjustFontSize` | Increase or decrease font size | `delta` (integer, required, e.g., `1` or `-1`) |
| `adjustOpacity` | Change window opacity | `opacity` (integer, -100 to 100), `relative` (boolean, default `true`) |
| `clearAllMarks` | Remove all scroll marks | (none) |
| `clearBuffer` | Clear screen and/or scrollback | `clear`: `"all"`, `"screen"`, or `"scrollback"` |
| `clearMark` | Clear the mark at the current position | (none) |
| `closeOtherPanes` | Close all panes except the focused one | (none) |
| `closeOtherTabs` | Close all tabs except the specified one | `index` (integer/null, default: focused tab) |
| `closePane` | Close the focused pane | (none) |
| `closeTab` | Close a specific tab | `index` (integer/null, default: focused tab) |
| `closeTabsAfter` | Close all tabs after the specified index | `index` (integer/null, default: focused tab) |
| `closeWindow` | Close the entire window | (none) |
| `commandPalette` | Open the command palette | `launchMode`: `"action"` or `"commandLine"` |
| `copy` | Copy selected text to clipboard | `singleLine`, `copyFormatting`, `dismissSelection`, `withControlSequences` |
| `duplicateTab` | Duplicate the current tab | (none) |
| `expandSelectionToWord` | Expand the current selection to word boundaries | (none) |
| `experimental.colorSelection` | Color the selected text | `matchMode` (`"none"` or `"all"`), `foreground`, `background` |
| `exportBuffer` | Export the terminal buffer to a file | `path` (string, opens file picker if empty) |
| `find` | Open the search dialog | (none) |
| `findMatch` | Navigate between search results | `direction`: `"next"` or `"prev"` (required) |
| `focusPane` | Focus a pane by its ID | `id` (integer, required) |
| `globalSummon` | Summon the Terminal window from anywhere | `desktop`, `monitor`, `name`, `dropdownDuration`, `toggleVisibility` |
| `identifyWindow` | Show the current window's name/ID overlay | (none) |
| `identifyWindows` | Show name/ID overlay on all Terminal windows | (none) |
| `markMode` | Enter mark mode for keyboard-driven selection | (none) |
| `moveFocus` | Move focus between panes | `direction` (required): `"left"`, `"right"`, `"up"`, `"down"`, `"previous"`, `"nextInOrder"`, `"previousInOrder"`, `"first"`, `"parent"`, `"child"` |
| `movePane` | Move the focused pane to another tab | `index` (integer, required) |
| `moveTab` | Move the current tab left or right | `direction`: `"forward"` or `"backward"` (required) |
| `multipleActions` | Execute a sequence of actions | `actions` (array, required) |
| `newTab` | Open a new tab | Accepts all `NewTerminalArgs`: `profile`, `commandline`, `startingDirectory`, `tabTitle`, `tabColor`, `colorScheme`, `elevate`, `index`, `suppressApplicationTitle`, `reloadEnvironmentVariables` |
| `newWindow` | Open a new Terminal window | Same args as `newTab` |
| `nextTab` | Switch to the next tab | `tabSwitcherMode`: `"mru"`, `"inOrder"`, `"disabled"` |
| `openAbout` | Open the About dialog | (none) |
| `openCWD` | Open the current working directory in File Explorer | (none) |
| `openNewTabDropdown` | Open the new tab dropdown menu | (none) |
| `openSettings` | Open settings | `target`: `"settingsUI"`, `"settingsFile"`, `"defaultsFile"`, `"allFiles"` |
| `openSystemMenu` | Open the system menu (window context menu) | (none) |
| `openTabColorPicker` | Open the tab color picker | (none) |
| `openTabRenamer` | Open the tab rename text box | (none) |
| `openWindowRenamer` | Open the window rename dialog | (none) |
| `paste` | Paste from clipboard | (none) |
| `prevTab` | Switch to the previous tab | `tabSwitcherMode`: `"mru"`, `"inOrder"`, `"disabled"` |
| `quakeMode` | Toggle the quake-mode dropdown window | (none) |
| `quit` | Close all Terminal windows | (none) |
| `renameTab` | Set a tab title programmatically | `title` (string, omit to restore original title) |
| `renameWindow` | Set the window name | `name` (string) |
| `resetFontSize` | Reset font size to the profile default | (none) |
| `resizePane` | Resize the focused pane | `direction`: `"left"`, `"right"`, `"up"`, `"down"` (required) |
| `restoreLastClosed` | Reopen the most recently closed tab or pane | (none) |
| `scrollDown` | Scroll down | `rowsToScroll` (integer/null, system default if omitted) |
| `scrollDownPage` | Scroll down one page | (none) |
| `scrollToBottom` | Scroll to the bottom of the buffer | (none) |
| `scrollToMark` | Scroll to a mark | `direction`: `"previous"`, `"next"`, `"first"`, `"last"` (required) |
| `scrollToTop` | Scroll to the top of the buffer | (none) |
| `scrollUp` | Scroll up | `rowsToScroll` (integer/null, system default if omitted) |
| `scrollUpPage` | Scroll up one page | (none) |
| `searchWeb` | Search the web for selected text | `queryUrl` (string with `%s` placeholder, required) |
| `selectAll` | Select all text in the buffer | (none) |
| `sendInput` | Send text input to the shell | `input` (string, required, supports `\u001b` for ESC) |
| `setColorScheme` | Change the active pane's color scheme | `colorScheme` (string, required) |
| `setFocusMode` | Set focus mode state | `isFocusMode` (boolean) |
| `setFullScreen` | Set fullscreen state | `isFullScreen` (boolean) |
| `setMaximized` | Set maximized state | `isMaximized` (boolean) |
| `setTabColor` | Set tab color programmatically | `color` (`#rrggbb` or null to reset) |
| `showSuggestions` | Open the suggestions overlay | `source`, `useCommandline` |
| `splitPane` | Split the current pane | `split` (`"auto"`, `"up"`, `"down"`, `"left"`, `"right"`), `size` (0-1), `splitMode` (`"duplicate"`), plus all `NewTerminalArgs` |
| `swapPane` | Swap the focused pane with an adjacent one | `direction` (same values as `moveFocus`, required) |
| `switchSelectionEndpoint` | Move the active selection endpoint | (none) |
| `switchToTab` | Switch to a tab by index | `index` (integer, 0-based, required) |
| `tabSearch` | Open the tab search dialog | (none) |
| `toggleAlwaysOnTop` | Toggle always-on-top mode | (none) |
| `toggleBlockSelection` | Toggle block (rectangular) selection mode | (none) |
| `toggleFocusMode` | Toggle focus mode (hide tabs/title bar) | (none) |
| `toggleFullscreen` | Toggle fullscreen mode | (none) |
| `togglePaneZoom` | Toggle zoom on the focused pane | (none) |
| `toggleReadOnlyMode` | Toggle read-only mode for the pane | (none) |
| `toggleShaderEffects` | Toggle pixel shader / retro effects | (none) |
| `toggleSplitOrientation` | Toggle split between horizontal and vertical | (none) |
| `wt` | Execute a `wt` command line in the current window | `commandline` (string, required) |
| `unbound` | Explicitly unbind a key combination | (none) |

> [!IMPORTANT]
> Actions with `(none)` in the Key Arguments column take no parameters. Actions marked `(required)` will fail silently if the required argument is missing. Use the Settings UI or JSON schema validation to catch configuration errors.

### Keybindings

Keybindings are defined in the `keybindings` array and map key chords to action IDs. The format supports multi-key chords (pressing keys in sequence):

```json
"keybindings": [
    { "keys": "ctrl+shift+t", "id": "Terminal.OpenNewTab" },
    { "keys": ["ctrl+k", "ctrl+p"], "id": "Terminal.CommandPalette" },
    { "keys": "ctrl+shift+w", "id": null }
]
```

Setting `"id": null` unbinds a key. Key chord modifiers are `ctrl`, `alt`, `shift`, and `win`. Keys can be named (`backspace`, `delete`, `enter`, `esc`, `tab`, `space`, `up`, `down`, `left`, `right`, `home`, `end`, `pageup`, `pagedown`, `f1`-`f24`, `plus`, `minus`, `comma`, `period`) or single characters.

Virtual key codes and scan codes are also supported: `vk(nnn)` and `sc(nnn)`.

### New Tab Menu Customization

The `newTabMenu` property controls the structure of the dropdown menu that appears when clicking the `+` button or the dropdown arrow:

```json
"newTabMenu": [
    { "type": "profile", "profile": "PowerShell" },
    { "type": "profile", "profile": "Ubuntu" },
    { "type": "separator" },
    {
        "type": "folder",
        "name": "SSH Sessions",
        "icon": "\uE8AF",
        "entries": [
            { "type": "profile", "profile": "SSH Production" },
            { "type": "profile", "profile": "SSH Staging" }
        ]
    },
    { "type": "separator" },
    { "type": "remainingProfiles" }
]
```

Entry types:
- `profile` -- a specific profile by name or GUID
- `folder` -- a submenu with nested entries, an `icon`, and optional `inline` behavior (`"auto"` collapses single-entry folders)
- `separator` -- a visual divider
- `remainingProfiles` -- all profiles not already listed (use at most once)
- `matchProfiles` -- profiles matching a `name`, `source`, or `commandline` pattern
- `action` -- an action referenced by ID
- `source` -- profiles from a specific dynamic source

> [!CAUTION]
> Using `remainingProfiles` more than once in the `newTabMenu` causes a crash (Access Violation in Settings.Model.dll). This is a known issue (GitHub #20124). Ensure you have exactly zero or one `remainingProfiles` entry.

---

## 5. Common Tasks

### Custom Keybindings

To add or override keybindings, add entries to the `actions` or `keybindings` array in `settings.json`.

**Example: Bind Ctrl+Shift+E to split right with the default profile:**

```json
"actions": [
    {
        "command": {
            "action": "splitPane",
            "split": "right"
        },
        "keys": "ctrl+shift+e",
        "id": "User.SplitRight"
    }
]
```

**Example: Unbind a default keybinding:**

```json
"keybindings": [
    { "keys": "ctrl+shift+t", "id": null }
]
```

**Example: Multi-key chord (press Ctrl+K, then Ctrl+O):**

```json
"keybindings": [
    { "keys": ["ctrl+k", "ctrl+o"], "id": "User.OpenCWD" }
]
```

### Creating a WSL Profile

WSL distributions are usually auto-detected, but you can create one manually:

```json
{
    "name": "Ubuntu 22.04",
    "commandline": "wsl.exe -d Ubuntu-22.04",
    "startingDirectory": "\\\\wsl$\\Ubuntu-22.04\\home\\username",
    "icon": "ms-appx:///ProfileIcons/{9acb9455-ca41-5af7-950f-6bca1bc9722f}.png",
    "colorScheme": "One Half Dark",
    "pathTranslationStyle": "wsl"
}
```

Setting `pathTranslationStyle` to `"wsl"` ensures that Windows paths dragged onto the terminal are automatically converted to `/mnt/c/...` format.

### Creating an SSH Profile

```json
{
    "name": "Production Server",
    "commandline": "ssh [email removed]",
    "icon": "\uD83D\uDD12",
    "colorScheme": "Solarized Dark",
    "tabColor": "#FF6347"
}
```

### Setting Up Color Schemes

1. Find or create a scheme (many are available at community sites).
2. Add it to the `schemes` array in `settings.json`.
3. Reference it in your profile with `"colorScheme": "SchemeName"`.
4. For automatic dark/light switching, use:

```json
"colorScheme": {
    "dark": "One Half Dark",
    "light": "One Half Light"
}
```

### Background Images

```json
{
    "backgroundImage": "C:\\Users\\me\\Pictures\\wallpaper.jpg",
    "backgroundImageOpacity": 0.3,
    "backgroundImageStretchMode": "uniformToFill",
    "backgroundImageAlignment": "center"
}
```

Use `"desktopWallpaper"` as the value to mirror your current desktop wallpaper:

```json
{
    "backgroundImage": "desktopWallpaper",
    "backgroundImageOpacity": 0.15
}
```

### Quake Mode Setup

Quake mode provides a drop-down terminal that slides in from the top of the screen, toggled by a global hotkey. It works out of the box with `Win+`` ` (backtick).

For the dropdown animation, use `globalSummon` with a `dropdownDuration`:

```json
{
    "command": {
        "action": "globalSummon",
        "name": "_quake",
        "dropdownDuration": 200,
        "toggleVisibility": true,
        "monitor": "toMouse",
        "desktop": "toCurrent"
    },
    "keys": "win+`"
}
```

To keep quake mode running even after closing all other windows, set `"compatibility.allowHeadless": true` in global settings.

> [!WARNING]
> A known issue (GitHub #20056) causes quake mode to leave an empty tray icon after the window is closed. This is cosmetic and does not affect functionality.

### Startup Actions

Launch multiple tabs and panes automatically when Terminal starts:

```json
"startupActions": "new-tab -p \"PowerShell\" ; split-pane -H -p \"Ubuntu\" ; new-tab -p \"cmd\""
```

This uses the same syntax as `wt` command-line arguments.

### Environment Variables Per Profile

```json
{
    "name": "Dev Environment",
    "commandline": "powershell.exe",
    "environment": {
        "NODE_ENV": "development",
        "RUST_LOG": "debug",
        "PATH": "%PATH%;C:\\my-tools\\bin"
    }
}
```

Environment variable values can reference existing variables using `%VARNAME%` syntax.

### Font Customization

```json
"font": {
    "face": "Cascadia Code",
    "size": 14,
    "weight": "semi-light",
    "features": {
        "ss01": 1,
        "liga": 1
    }
}
```

**Font features** use four-character OpenType tags. Common ones:
- `liga` -- standard ligatures (e.g., `!=` becomes a single glyph in supporting fonts)
- `ss01` through `ss20` -- stylistic sets (font-specific alternates)
- `calt` -- contextual alternates

**Variable font axes** use `font.axes` (e.g., `{"wght": 350}` for a non-standard weight).

### Tab Colors

Set a persistent color per profile:

```json
"tabColor": "#E06C75"
```

Or set it at runtime using the `setTabColor` action:

```json
{
    "command": {
        "action": "setTabColor",
        "color": "#61AFEF"
    },
    "keys": "ctrl+shift+g"
}
```

Pass `null` for the color to reset to the default.

### Elevating (Running as Administrator)

Set `"elevate": true` on a profile to always open it in an elevated context. When the current Terminal window is not elevated, a new elevated window is spawned with a UAC prompt.

### Drag-and-Drop Path Translation

When dragging files from File Explorer into a WSL, Cygwin, or MSYS2 pane, set the `pathTranslationStyle` so that `C:\Users\...` is automatically converted:

| Style | Example Output |
|---|---|
| `"none"` | `C:\Users\me\file.txt` |
| `"wsl"` | `/mnt/c/Users/me/file.txt` |
| `"cygwin"` | `/cygdrive/c/Users/me/file.txt` |
| `"msys2"` | `/c/Users/me/file.txt` |
| `"mingw"` | `/c/Users/me/file.txt` |

The `dragDropDelimiter` setting controls the separator when dropping multiple files (default is a space).

### Shell Integration and Marks

Shell integration lets Windows Terminal understand command boundaries, which enables:
- Automatic prompt marking (`autoMarkPrompts`)
- Scrollbar marks showing command locations (`showMarksOnScrollbar`)
- Scroll-to-mark navigation
- Suggestions from command history

Shell integration is configured in your shell's profile (e.g., `~/.bashrc`, PowerShell `$PROFILE`). PowerShell 7.4+ includes built-in support. For other shells, follow the shell integration documentation for your specific shell.

Manual marks can be added with the `addMark` action and cleared with `clearMark` or `clearAllMarks`.

### Exporting the Buffer

Save the entire terminal scrollback to a text file:

```json
{
    "command": {
        "action": "exportBuffer",
        "path": "C:\\logs\\terminal-output.txt"
    },
    "keys": "ctrl+shift+x"
}
```

If `path` is empty, a file picker dialog opens.

### Custom Pixel Shaders

Windows Terminal can apply custom HLSL pixel shaders to the terminal output. Example shaders are available in the `samples/PixelShaders/` directory of the repository.

```json
{
    "experimental.pixelShaderPath": "C:\\shaders\\my-effect.hlsl"
}
```

Toggle shader effects at runtime with the `toggleShaderEffects` action.

### Multiple Actions on One Keybinding

Bind a single key chord to execute a sequence of actions:

```json
{
    "command": {
        "action": "multipleActions",
        "actions": [
            { "action": "copy" },
            { "action": "closePane" }
        ]
    },
    "keys": "ctrl+shift+x"
}
```

### Send Input (Macros)

Send arbitrary text or escape sequences to the shell:

```json
{
    "command": {
        "action": "sendInput",
        "input": "git status\r"
    },
    "keys": "ctrl+shift+g"
}
```

Use `\u001b` for the Escape character in ANSI sequences:

```json
{
    "command": {
        "action": "sendInput",
        "input": "\u001b[A"
    },
    "keys": "ctrl+shift+up"
}
```

### Right-Click Context Menu

By default, right-clicking pastes from the clipboard (or copies the selection). To get a context menu instead:

```json
"experimental.rightClickContextMenu": true
```

### Clearing the Buffer

```json
{
    "command": {
        "action": "clearBuffer",
        "clear": "all"
    },
    "keys": "ctrl+shift+k"
}
```

Options: `"all"` (screen + scrollback), `"screen"` (visible area only), `"scrollback"` (scrollback only).

### Opening the Current Working Directory

The `openCWD` action opens File Explorer at the terminal's current working directory. This requires shell integration to be enabled so Terminal knows the current directory.

### Persisted Window Layout

To restore your tabs and panes when Terminal reopens:

```json
"firstWindowPreference": "persistedWindowLayout"
```

Terminal saves the window layout on close and restores it on the next launch.

### Iterable Commands

Create commands that dynamically expand for each profile or color scheme:

```json
{
    "iterateOn": "profiles",
    "name": "Switch to ${profile.name}",
    "command": {
        "action": "newTab",
        "profile": "${profile.name}"
    }
}
```

This generates one command palette entry for every profile.

### Global Summon (Custom Hotkey to Summon Terminal)

Beyond quake mode, `globalSummon` provides fine-grained control over how the Terminal window is summoned:

```json
{
    "command": {
        "action": "globalSummon",
        "desktop": "toCurrent",
        "monitor": "toMouse",
        "toggleVisibility": true
    },
    "keys": "ctrl+`"
}
```

Parameters:
- `desktop`: `"any"` (switch to the desktop where Terminal is), `"toCurrent"` (move Terminal to the current desktop), `"onCurrent"` (only summon if already on this desktop)
- `monitor`: `"any"`, `"toCurrent"`, `"toMouse"` (move to the monitor with the mouse cursor)
- `name`: summon a specific named window, or create one with that name if it does not exist
- `dropdownDuration`: milliseconds for a slide-in animation (0 for instant)
- `toggleVisibility`: when `true`, pressing the hotkey again minimizes the window

### Running Fullscreen Without Tabs

Combine fullscreen and focus mode for a distraction-free experience:

```json
"launchMode": "fullscreen",
"startupActions": ""
```

Or toggle at runtime:

```json
{
    "command": {
        "action": "multipleActions",
        "actions": [
            { "action": "toggleFullscreen" },
            { "action": "toggleFocusMode" }
        ]
    },
    "keys": "f11"
}
```

### Showing Fullscreen Tabs

By default, tabs are hidden in fullscreen. To keep them visible:

```json
"showTabsFullscreen": true
```

### Disabling Dynamic Profile Sources

To prevent Terminal from auto-detecting certain profile types:

```json
"disabledProfileSources": [
    "Windows.Terminal.Azure",
    "Windows.Terminal.VisualStudio"
]
```

Valid sources: `"Microsoft.WSL"`, `"Windows.Terminal.Wsl"`, `"Windows.Terminal.Azure"`, `"Windows.Terminal.PowershellCore"`, `"Windows.Terminal.VisualStudio"`.

---

## 6. Troubleshooting

### Settings not applying after saving

**Cause:** JSON syntax error in `settings.json`, or editing the wrong file.

**Solution:**
1. Open `settings.json` in VS Code or another editor with JSON validation.
2. Look for red squiggly underlines indicating syntax errors (trailing commas, missing quotes, unclosed braces).
3. Confirm you are editing the correct file for your install method (Store vs. unpackaged path).
4. Windows Terminal hot-reloads settings -- no restart is needed unless the error prevented loading.

**Prevention:** Use the Settings UI (`Ctrl+,`) for simple changes, and always validate JSON before saving.

### Fonts not rendering correctly or not found

**Cause:** The specified font is not installed system-wide, or the font name is misspelled.

**Solution:**
1. Open Windows Settings > Personalization > Fonts and confirm the font is installed.
2. Use the exact font family name (e.g., `"Cascadia Code"` not `"CascadiaCode"` or `"Cascadia Code Regular"`).
3. If using a Nerd Font, the family name often includes "Nerd Font" (e.g., `"FiraCode Nerd Font"`).
4. Reset to the default: `"font": { "face": "Cascadia Mono" }`.

**Prevention:** Test fonts in the Settings UI font picker, which shows only installed fonts.

### GPU rendering issues (blank screen, artifacts, flickering)

**Cause:** Incompatible or outdated GPU drivers, or issues with the Direct3D 11 renderer.

**Solution:**
1. Update your GPU drivers to the latest version.
2. Try switching the graphics API: `"rendering.graphicsAPI": "direct2d"`.
3. As a last resort, enable software rendering: `"rendering.software": true`.
4. If only partial rendering issues occur, try: `"rendering.disablePartialInvalidation": true`.

**Prevention:** Keep GPU drivers up to date.

> [!TIP]
> If you experience flickering only in the tab bar, this is a known issue (GitHub #14384) that affects both stable and preview versions. Switching `rendering.graphicsAPI` may help in some cases.

### WSL profiles not appearing

**Cause:** WSL is not installed, no distributions are installed, or the dynamic profile source is disabled.

**Solution:**
1. Confirm WSL is installed: `wsl --list --verbose`.
2. Install a distribution if none exists: `wsl --install -d Ubuntu`.
3. Check that `"disabledProfileSources"` in your settings does not include `"Windows.Terminal.Wsl"` or `"Microsoft.WSL"`.
4. Restart Windows Terminal.

**Prevention:** Do not add WSL to the `disabledProfileSources` array unless you intentionally want to hide WSL profiles.

### Error: Duplicate `remainingProfiles` in `newTabMenu` causes crash

**Cause:** Having more than one `{"type": "remainingProfiles"}` entry in the `newTabMenu` array triggers an Access Violation in Settings.Model.dll (GitHub #20124).

**Solution:**
1. Open `settings.json` and search for `remainingProfiles`.
2. Remove all but one instance.
3. Save and restart Terminal.

**Prevention:** Use at most one `remainingProfiles` entry in `newTabMenu`.

### Ubuntu icon disappeared from tabs and dropdown

**Cause:** Profile icon path references an icon that is no longer available or the profile generator icon mapping changed (GitHub #20126).

**Solution:**
1. Manually set the icon for the affected profile in `settings.json`:
   ```json
   "icon": "ms-appx:///ProfileIcons/{9acb9455-ca41-5af7-950f-6bca1bc9722f}.png"
   ```
2. Alternatively, use an emoji or a custom icon file path.

### Quake mode leaves an empty tray icon

**Cause:** Known issue (GitHub #20056) where closing the quake window does not fully clean up the notification area icon.

**Solution:** Right-click the empty tray icon and dismiss it, or restart Windows Terminal. The icon is cosmetic and does not affect other windows.

### Output slow for half a second, then fast

**Cause:** A rendering or input pipeline stall that resolves after the first buffer fill (GitHub #20113). May relate to shell startup scripts or the Direct3D swap chain initialization.

**Solution:**
1. Try `"rendering.graphicsAPI": "direct2d"`.
2. Reduce shell startup overhead (remove heavy `$PROFILE` scripts).
3. If the issue persists, check for background antivirus scanning of the shell executable.

### Half-width Katakana and (han)dakuten overlap

**Cause:** Combining characters in half-width Katakana are not correctly handled in the text layout engine (GitHub #18087).

**Solution:** No full fix yet. As a workaround, use full-width Katakana or set `"compatibility.textMeasurement": "wcswidth"` (may affect other Unicode rendering).

### Arrow keys not working for on-screen keyboard in certain tools

**Cause:** Regression affecting virtual keyboard input in interactive CLI tools (GitHub #20122).

**Solution:** Use a physical keyboard. If a virtual keyboard is required, consider running the tool in `conhost.exe` directly.

### New Actions / Quake Window broken

**Cause:** Settings migration issue where the actions or keybindings format is incompatible with a new version (GitHub #20119).

**Solution:**
1. Back up your `settings.json`.
2. Open Settings UI and check for error banners.
3. If errors are present, reset settings by deleting `settings.json` (it will be regenerated with defaults).
4. Re-apply your customizations.

### SGR 2 (Faint/Dim) is ineffective on light themes

**Cause:** The dimming algorithm reduces color intensity, which is visually imperceptible against a light background (GitHub #20109).

**Solution:** No fix currently available. Use a dark color scheme for content that relies on faint/dim text rendering.

### Alt+Tab adds an unwanted keyboard layout

**Cause:** When Terminal receives focus via Alt+Tab, the input system may register an additional keyboard layout (GitHub #14030).

**Solution:**
1. Check Windows Settings > Time & language > Language & region and remove unwanted keyboard layouts.
2. If the issue recurs, it is a Windows input method issue, not Terminal-specific.

### The `-d` CLI parameter is not shown in help

**Cause:** The `wt` command-line help text does not document the `-d` (starting directory) flag, though it is functional (GitHub #9585).

**Solution:** The flag works despite being undocumented. Usage:
```powershell
wt -d "C:\Projects"
```

### OSC 7 notifications from non-host connections

**Cause:** Remote sessions (SSH, containers) send OSC 7 (current directory) sequences with a hostname that does not match the local machine (GitHub #20072).

**Solution:** Terminal currently processes all OSC 7 sequences regardless of host. If this causes incorrect "Open CWD" behavior, disable shell integration's OSC 7 output in your remote shell's configuration.

### Tab bar flickering

**Cause:** A rendering race condition that causes the tab bar to flicker intermittently (GitHub #14384). Affects both stable and preview versions.

**Solution:**
1. Try different `rendering.graphicsAPI` values.
2. Update GPU drivers.
3. The issue is under active investigation by the Terminal team.

> [!WARNING]
> Do not modify `rendering.software: true` as a permanent solution for flickering -- it significantly degrades performance. Use it only for testing whether the issue is GPU-related.

### Terminal crashes on startup

**Cause:** Corrupted `settings.json` or an incompatible extension.

**Solution:**
1. Rename `settings.json` to `settings.json.bak`.
2. Launch Terminal -- it will regenerate a default `settings.json`.
3. Gradually re-apply your customizations, testing after each change.
4. If the crash persists, check for corrupted MSIX packages:
   ```powershell
   Get-AppxPackage Microsoft.WindowsTerminal | Remove-AppxPackage
   ```
   Then reinstall.

### Missing ColorTool releases

**Cause:** ColorTool releases are no longer published separately from the main Terminal repository (GitHub #20129).

**Solution:** Use the color scheme management built into Windows Terminal itself, or build ColorTool from source (`src/tools/ColorTool/` in the repository).

### Acrylic not working when window is unfocused

**Cause:** By default, acrylic is disabled when the window loses focus to save GPU resources.

**Solution:** Set `"compatibility.enableUnfocusedAcrylic": true` in global settings.

### `wt` command opens a new window instead of a tab

**Cause:** The default `windowingBehavior` is `"useNew"`.

**Solution:** Set `"windowingBehavior": "useExisting"` to open new tabs in the most recently used window on the current virtual desktop, or `"useAnyExisting"` for any desktop.

### Pasting triggers a large-paste warning for small text

**Cause:** The large-paste threshold is 5 KiB of characters.

**Solution:** If this is annoying for your workflow, disable it: `"warning.largePaste": false`. Similarly, `"warning.multiLinePaste": false` disables the newline warning.

### Background image not displaying

**Cause:** The image path is invalid, the file format is unsupported, or the opacity is too low.

**Solution:**
1. Use an absolute path with escaped backslashes: `"C:\\Users\\me\\image.jpg"`.
2. Supported formats: PNG, JPEG, GIF, BMP, ICO, TIFF.
3. Check that `backgroundImageOpacity` is greater than 0.
4. Try `"backgroundImageStretchMode": "uniformToFill"` if the image appears but is cropped unexpectedly.

### Profiles from Visual Studio not appearing

**Cause:** The `"Windows.Terminal.VisualStudio"` profile source may be disabled, or Visual Studio is not properly installed.

**Solution:** Ensure `disabledProfileSources` does not include `"Windows.Terminal.VisualStudio"`. Verify that Visual Studio Developer Command Prompt/PowerShell shortcuts exist in the Start menu.

### Path with spaces not handled correctly

**Cause:** Some command-line arguments do not properly handle paths containing spaces (GitHub #20107).

**Solution:** Wrap paths in double quotes when using `wt` command-line arguments:
```powershell
wt -d "C:\Program Files\My App"
```

> [!NOTE]
> When editing `settings.json`, remember that JSON strings require backslashes to be escaped as `\\`. A path like `C:\Users` must be written as `"C:\\Users"`.

### Korean IME composing character hides adjacent character

**Cause:** A rendering issue with Korean IME composition (GitHub #20040, fixed in recent versions).

**Solution:** Update to the latest version of Windows Terminal.

### Terminal window appears off-screen

**Cause:** The `initialPosition` setting references coordinates on a monitor that is no longer connected.

**Solution:**
1. Delete the `initialPosition` property from `settings.json`.
2. Set `"centerOnLaunch": true` to center the window on the primary display.
3. Alternatively, use `Win+Left Arrow` or `Win+Right Arrow` to snap the window to the current display.

### Scrollback history lost after closing a tab

**Cause:** Terminal does not persist scrollback between sessions. When a tab or pane is closed, the buffer is discarded.

**Solution:** Use `exportBuffer` to save the scrollback before closing. For persistent logging, configure your shell to log output to a file.

**Prevention:** Set a generous `historySize` (default is 9001 lines) and use `exportBuffer` before closing important sessions.

### Settings UI shows errors or crashes

**Cause:** Invalid or conflicting entries in `settings.json` that the Settings UI cannot parse.

**Solution:**
1. Open `settings.json` directly with a text editor.
2. Fix JSON syntax errors.
3. Look for deprecated property names and update them (e.g., `"acrylicOpacity"` should be `"opacity"`).

---

## 7. FAQ

### General

**What is Windows Terminal?**
Windows Terminal is Microsoft's modern, open-source terminal application for Windows 10 and 11. It provides tabs, panes, GPU-accelerated rendering, Unicode support, and extensive customization. It is not a shell itself -- it is a host that runs shells like PowerShell, Command Prompt, WSL, and others.

**Is Windows Terminal free?**
Yes. Windows Terminal is free and open source under the MIT license. Both the stable and preview versions are free.

**What is the difference between Windows Terminal and Windows Terminal Preview?**
Windows Terminal Preview receives new features and changes before they are released to the stable version. Both can be installed side by side. Use Preview if you want early access to new features; use Stable for production reliability.

**Does Windows Terminal replace Command Prompt or PowerShell?**
No. Windows Terminal is a terminal emulator that hosts these shells. Command Prompt (`cmd.exe`) and PowerShell continue to exist as separate programs. Terminal provides a modern interface for running them.

**Can I use Windows Terminal on Windows Server?**
Windows Terminal requires Windows 10 1903 or later. Windows Server 2022 and later can run Terminal, but it may require manual installation via the MSIX bundle since the Microsoft Store may not be available.

**What shells can Windows Terminal run?**
Any command-line application: PowerShell (5.1 and 7+), Command Prompt, WSL (all distributions), Azure Cloud Shell, Git Bash, Cygwin, MSYS2, SSH sessions, Python REPL, Node.js REPL, and more. If it runs in a console, Terminal can host it.

**What is conhost.exe and how does it relate to Windows Terminal?**
`conhost.exe` is the legacy Windows console host. Windows Terminal and conhost share the same repository and many internal components (ConPTY, virtual terminal support), but Terminal provides the modern UI experience. ConPTY is the pseudo-console layer that lets Terminal host traditional console applications.

### Installation

**How do I check which version I have installed?**
Run `wt --version` from any command line, or open the About dialog from the dropdown menu or via the `openAbout` action.

**How do I update Windows Terminal?**
Microsoft Store installs update automatically. For winget installs, run `winget upgrade --id Microsoft.WindowsTerminal`. For manual installs, download and install the latest `.msixbundle` from GitHub releases.

**Can I run both stable and preview versions simultaneously?**
Yes. They are separate applications with separate settings files and can run at the same time.

**Is Windows Terminal available for Windows 10 LTSC?**
Windows 10 LTSC 2019 (build 17763) does not meet the 1903 build requirement. LTSC 2021 (build 19044) and later support Windows Terminal.

### Configuration

**Where is my settings file?**
For Store/winget installs: `%LOCALAPPDATA%\Packages\Microsoft.WindowsTerminal_8wekyb3d8bbwe\LocalState\settings.json`. For unpackaged installs: `%LOCALAPPDATA%\Microsoft\Windows Terminal\settings.json`. Press `Ctrl+Shift+,` to open it directly.

**How do I reset settings to defaults?**
Delete or rename your `settings.json` file. Windows Terminal will regenerate it with default values on next launch.

**Can I sync settings across machines?**
The settings file is a single JSON file that can be synced via cloud storage, symlinks, or version control. Place it in a synced folder and create a symbolic link at the expected path.

**What is `profiles.defaults` for?**
Settings in `profiles.defaults` apply to every profile. They act as a base that individual profiles can override. This avoids duplicating settings like font configuration across every profile.

**How do I make PowerShell 7 (pwsh) the default profile?**
Find the PowerShell 7 profile's GUID in the profiles list (or its name), then set `"defaultProfile"` to that GUID or name.

**What happens if my settings.json has errors?**
Windows Terminal will attempt to load the file and will show a warning banner at the top of the window if errors are found. It falls back to default values for settings it cannot parse.

**Can I have separate settings for stable and preview?**
Yes. They use different settings file paths and do not share configuration.

### Appearance

**How do I make the terminal transparent?**
Set `"opacity"` to a value less than 100 in the profile settings. For the frosted glass effect, also set `"useAcrylic": true`. You can adjust opacity at runtime with `Ctrl+Shift+Scroll` (when `experimental.scrollToChangeOpacity` is `true`).

**How do I change the font?**
Set `"font": { "face": "Font Name", "size": 14 }` in your profile or in `profiles.defaults`. Use the Settings UI font picker to see available fonts.

**What is the default color scheme?**
Campbell. It is a dark scheme included with Windows Terminal. Nine built-in schemes are available: Campbell, Campbell Powershell, One Half Dark, One Half Light, Solarized Dark, Solarized Light, Tango Dark, Tango Light, and Vintage.

**Can I have different appearances when a pane is unfocused?**
Yes. Set the `unfocusedAppearance` property on a profile to an object containing appearance settings (color scheme, opacity, cursor shape, background image, etc.).

**How do I use Mica material?**
In your theme definition, set `"window": { "useMica": true }`. This requires Windows 11.

**How do I set a different color scheme for light and dark mode?**
Use the `SchemePair` syntax: `"colorScheme": { "dark": "One Half Dark", "light": "One Half Light" }`. The Terminal switches automatically based on the OS theme.

**What cursor shapes are available?**
Six shapes: `"bar"` (default, a thin vertical line), `"underscore"` (a thin horizontal line at the bottom), `"doubleUnderscore"` (two horizontal lines), `"filledBox"` (a solid block), `"emptyBox"` (a hollow block), and `"vintage"` (a thick block with adjustable height via `cursorHeight`).

### Usage

**How do I split the screen into multiple panes?**
Press `Alt+Shift+Plus` for a vertical split or `Alt+Shift+Minus` for a horizontal split. Navigate between panes with `Alt+Arrow` keys.

**How do I open a new tab with a specific profile?**
Press `Ctrl+Shift+1` through `Ctrl+Shift+9` to open by profile index (matching the order in the dropdown). Or use the dropdown menu to select a profile.

**How do I copy and paste?**
Select text with the mouse, then press `Ctrl+Shift+C` (or just `Ctrl+C` if text is selected). Paste with `Ctrl+Shift+V` (or `Ctrl+V`). Enable `"copyOnSelect": true` to copy automatically on selection.

**What is the Command Palette?**
Press `Ctrl+Shift+P` to open a searchable list of all available actions. Type to filter, then press Enter to execute.

**What is quake mode?**
A drop-down terminal window that slides in from the top of the screen when you press `Win+`` ` (backtick). It provides instant access to a terminal from any application. See Common Tasks for setup details.

**How do I search within the terminal output?**
Press `Ctrl+Shift+F` to open the search box. Type your query and use the arrow buttons or `findMatch` bindings to navigate matches.

**Can I run a command automatically when Terminal starts?**
Yes. Set `"startupActions"` in your global settings to a `wt` command-line string. For example: `"new-tab -p PowerShell ; split-pane -p Ubuntu"`.

**How do I send the same input to multiple panes?**
Broadcast input is not a built-in feature. You can simulate it using the `sendInput` action bound to keybindings, but true simultaneous broadcast is not supported as a native action.

**How do I export my terminal output to a file?**
Use the `exportBuffer` action. Bind it to a key and optionally set a `path`. If no path is given, a file save dialog appears.

**What are marks?**
Marks are positions in the scrollback buffer that you can jump between. They can be added manually via `addMark` or automatically via shell integration (`autoMarkPrompts`). Marks can optionally appear on the scrollbar with `showMarksOnScrollbar`.

**What is the `.wt.json` file?**
A project-specific configuration file that defines command snippets (tasks). When placed in a directory, its snippets appear in the suggestions UI while you are working in that directory or its children.

**Can I restore a closed tab?**
Yes, if you bind the `restoreLastClosed` action to a keybinding. It reopens the most recently closed tab or pane.

**How does `windowingBehavior` work?**
`"useNew"` (default) always opens a new window. `"useExisting"` opens a new tab in the most recently used Terminal window on the current virtual desktop. `"useAnyExisting"` opens a tab in the most recently used window on any desktop.

**How do I zoom a single pane to fill the window?**
Use the `togglePaneZoom` action. Press it again to restore the original pane layout.

### Troubleshooting

**Terminal opens but shows a blank or white screen.**
Try switching to `"rendering.graphicsAPI": "direct2d"` or enabling `"rendering.software": true`. Update your GPU drivers.

**My custom settings are not taking effect.**
Check for JSON syntax errors. Windows Terminal silently ignores invalid JSON and falls back to defaults. Use a JSON validator or the Settings UI.

**The `wt` command is not recognized.**
Restart your shell after installing Terminal. Check that the "Windows Terminal" app execution alias is enabled in Windows Settings > Apps > App execution aliases.

**Terminal feels slow.**
Disable `useAcrylic` and any pixel shaders. Reduce `historySize` if it is set very high. Switch `rendering.graphicsAPI` to `"direct3d11"`. Ensure the terminal is not running under a remote desktop session (GPU acceleration may not be available).

**Can I downgrade to a previous version?**
Uninstall the current version, then install the desired version from a specific GitHub release `.msixbundle`. Microsoft Store does not support version pinning.

---

_Generated May 2026 from microsoft/terminal at 7a83c0f. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._