Main > Live (#644)

* fix(powerline): update oh-my-posh CLI (#632)

* Themes updates for 1.17 (#634)

Documents a whole pile of stuff from 1.17:

* `useMica` microsoft/terminal#13935
* theme pairs microsoft/terminal#14497
* scheme pairs microsoft/terminal#14064
* closes #626

* Default prompt icon info, resolves #625 (#642)

* Add app execution alias section (#643)

* Add autoHideWindows

Resolves #633

* Add color theme FAQs

* Remove code brackets from headers

Resolves #637

* Fix default if no command specified

Called out in #638

* Add note differentiating null from no setting 

for Starting Directory. 
Resolves #624

---------

Co-authored-by: Jan De Dobbeleer <[email protected]>
Co-authored-by: Mike Griese <[email protected]>

TerminalDocs/command-line-arguments.md

@@ -3,7 +3,7 @@ title: Windows Terminal command line arguments
 description: Learn how to create command line arguments for Windows Terminal.
 author: cinnamon-msft
 ms.author: cinnamon
-ms.date: 05/24/2022
+ms.date: 03/10/2023
 ms.topic: how-to
 ---
 
@@ -18,7 +18,7 @@ You can use `wt.exe` to open a new instance of Windows Terminal from the command
 
 ## Command line syntax
 
-The `wt` command line accepts two types of values: **options** and **commands**. **Options** are a list of flags and other parameters that can control the behavior of the `wt` command line as a whole. **Commands** provide the action, or list of actions separated by semicolons, that should be implemented. If no command is specified, then the command is assumed to be `new-window` by default.
+The `wt` command line accepts two types of values: **options** and **commands**. **Options** are a list of flags and other parameters that can control the behavior of the `wt` command line as a whole. **Commands** provide the action, or list of actions separated by semicolons, that should be implemented. If no command is specified, then the command is assumed to be `new-tab` by default.
 
 ```cmd
 wt [options] [command ; ]
@@ -41,7 +41,7 @@ Below is the full list of supported commands and options for the `wt` command li
 | `--focus`, `-f` | Launches the terminal in the focus mode. Can be combined with `maximized`. |
 | `--window`, `-w` `<window-id>` | Launches the terminal in a specific window. |
 
-### `New-tab` command
+### New tab command
 
 | Command | Parameter | Description | Values |
 | ------- | ---------- | ----------- | ------ |
@@ -54,7 +54,7 @@ Below is the full list of supported commands and options for the `wt` command li
 > [!TIP]
 > If you change the title of a tab in Windows Terminal and want that title to persist, you must enable the [suppressApplicationTitle](./customize-settings/profile-advanced.md#suppress-title-changes) option by setting it to `true`.
 
-### `Split-pane` command
+### Split-pane command
 
 | Command | Parameter | Description | Values |
 | ------- | ---------- | ----------- | ------ |
@@ -67,13 +67,13 @@ Below is the full list of supported commands and options for the `wt` command li
 | `split-pane`, `sp` | `commandline` | Creates a new split window pane based on the assigned command line. | Executable with optional commands  |
 | `split-pane`, `sp` | `--duplicate, -D` | Creates a new split window pane that is a duplicate of the current pane. | N/A. No additional values to assign. |
 
-### `Focus-tab` command
+### Focus-tab command
 
 | Command | Parameter | Description | Values |
 | ------- | ---------- | ----------- | ------ |
 | `focus-tab`, `ft` |  `--target, -t tab-index` | Focuses on a specific tab according to it's tab index number. | Tab index as an integer |
 
-### `Move-focus` command
+### Move-focus command
 
 | Command | Parameter | Description | Values |
 | ------- | ---------- | ----------- | ------ |
@@ -530,3 +530,11 @@ wt --% new-tab cmd ; split-pane -p "Windows PowerShell" ; split-pane -H wsl.exe
 In both of these examples, the newly created Windows Terminal window will create the window by correctly parsing all the provided command-line arguments.
 
 However, these methods are _not_ recommended currently, as PowerShell will wait for the newly-created terminal window to be closed before returning control to PowerShell. By default, PowerShell will always wait for Windows Store applications (like Windows Terminal) to close before returning to the prompt. Note that this is different than the behavior of Command Prompt, which will return to the prompt immediately.
+
+## Add Windows Terminal executable to your PATH
+
+To add the Windows Terminal executable file (wt.exe) to your PATH, enable its "app execution alias" in the **Manage app execution aliases** page of Windows Settings. The Windows Terminal alias is turned on by default, but may be worth confirming if you're having issues accessing it.
+
+If you are still having trouble accessing app execution aliases, you might need to check whether your PATH contains: `%LOCALAPPDATA%\Microsoft\WindowsApps`. Do not attempt to make changes to `C:\Program Files\WindowsApps`.
+
+![Windows Settings for App Execution Aliases](./images/settings-app-execution-aliases.png)

TerminalDocs/custom-terminal-gallery/theme-gallery.md

@@ -64,3 +64,40 @@ Below are some examples of [Themes](./../customize-settings/themes.md).
 
 (Color scheme is based on [Fun Forrest](https://github.com/mbadolato/iTerm2-Color-Schemes/blob/master/windowsterminal/FunForrest.json))
 
+## Chonk
+
+![Windows Terminal Chonk Theme](./../images/Chonk-Theme.png)
+
+For best results, this theme is combined with the global settings `"alwaysShowTabs": true` and `"showTabsInTitlebar": false`, and a profile `opacity` of `0`. You may also want to disable the "Show accent color on title bars and windows borders" setting in the Windows settings app (under "Personalization > Colors")
+
+```json
+    "profiles": {
+        "defaults": {
+            "opacity": 0
+        }
+    },
+    "alwaysShowTabs": true,
+    "showTabsInTitlebar": false,
+    "theme": "chonk",
+    "themes": [
+        {
+            "name": "chonk",
+            "tab":
+            {
+                "background": "#00000000",
+                "unfocusedBackground": "#00000000",
+                "showCloseButton": "hover"
+            },
+            "tabRow":
+            {
+                "background": "#00000000",
+                "unfocusedBackground": "#00000000",
+            },
+            "window":
+            {
+                "applicationTheme": "dark",
+                "useMica": true
+            }
+        }
+    ]
+```

TerminalDocs/customize-settings/interaction.md

@@ -3,7 +3,7 @@ title: Windows Terminal Interaction Settings
 description: Learn how to customize interaction settings within Windows Terminal.
 author: cinnamon-msft
 ms.author: cinnamon
-ms.date: 05/24/2022
+ms.date: 03/10/2023
 ms.topic: how-to
 ---
 
@@ -204,6 +204,21 @@ The tab switcher will open on the initial press of the actions for `nextTab` and
 
 ___
 
+## Automatically hide on focus loss
+
+When enabled, this allows the Terminal window to automatically be hidden as soon as the window loses focus.
+
+**Property name:** `autoHideWindow`
+
+**Necessity:** Optional
+
+**Accepts:** `true`, `false`
+
+**Default value:** `false`
+
+<br />
+___
+
 ## Automatically focus pane on mouse hover
 
 When this is set to `true`, the terminal will move focus to the pane on mouse hover. When it's set to `false`, a click will be required to focus the pane using the mouse.

TerminalDocs/customize-settings/profile-appearance.md

@@ -28,14 +28,30 @@ The settings listed below affect the visual settings of each profile separately.
 
 This is the name of the color scheme used in the profile. Color schemes are defined in the `schemes` object. More detailed information can be found on the [Color schemes page](./color-schemes.md).
 
+In addition to a single color scheme name, this property can accept a pair of color scheme names as follows:
+
+```json
+"colorScheme":
+{
+    "light": "One Half Light",
+    "dark": "One Half Dark",
+},
+```
+
+When specified in this manner, the Terminal will automatically switch between the two given color schemes depending on the theme of the application. The Terminal will follow the [`theme.applicationTheme`](./themes.md#application-theme) property of the Terminal's selected theme. If that `applicationTheme` is set to `system`, then this will instead use the color scheme matching the OS theme.
+
 **Property name:** `colorScheme`
 
 **Necessity:** Optional
 
-**Accepts:** Name of color scheme as a string
+**Accepts:** Name of color scheme as a string, or an object with a `light` and `dark` property
 
 **Default value:** `"Campbell"`
 
+
+> [!IMPORTANT]
+> Specifying a pair of `light` and `dark` color schemes is only available in [Windows Terminal Preview](https://aka.ms/terminal-preview).
+
 ### Font
 
 This is the structure within which the other font settings must be defined. An example of what this could look like in the JSON file is shown below.
@@ -261,6 +277,12 @@ Windows Terminal displays icons for each profile which the terminal generates fo
 
 Icons should be sized to 32x32px in an appropriate raster image format (e.g. .PNG, .GIF, or .ICO) to avoid having to scale your icons during runtime (causing a noticeable delay and loss of quality).
 
+If no icon is specified for a command line you've installed, Windows Terminal will default to this glyph from the [Segoe Fluent](/windows/apps/design/style/segoe-fluent-icons-font) font:
+
+Glyph	| Unicode point | Description
+--|--|--
+![Segoe Fluent command line icon](../images/segoe-commandline-icon.png) | e756 | CommandPrompt
+
 ### Background image stretch mode
 
 :::row:::
@@ -358,6 +380,9 @@ When `useAcrylic` is set to `true`, the window will use the acrylic material to
 > [!IMPORTANT]
 > Unblurred opacity (`"useAcrylic": false`) only works on Windows 11.
 
+> [!IMPORTANT]
+> When Mica is enabled in the [theme settings](./themes.md#mica), Mica will appear underneath the Terminal contents when the `opacity` of the Terminal is set to a value <100.
+
 ### Enable acrylic
 
 :::row:::

TerminalDocs/customize-settings/profile-general.md

@@ -3,7 +3,7 @@ title: Windows Terminal General Profile Settings
 description: Learn how to customize the general profile settings within Windows Terminal.
 author: cinnamon-msft
 ms.author: cinnamon
-ms.date: 05/24/2022
+ms.date: 03/10/2023
 ms.topic: how-to
 ---
 
@@ -64,6 +64,8 @@ This is the directory the shell starts in when it is loaded.
 
 **Default value:** `"%USERPROFILE%"`
 
+**NOTE:** When starting directory is not defined, the default value will be set to `"%USERPROFILE%"` (the path relative to your user settings, for example this may be `C:\Users\<your username>`). However, if the starting directory is explicitely set to `null`, then you will get different results depending on where you launch Terminal.
+
 **Example:** Start the PowerShell profile in the *GitHubRepos* folder of your *Documents* directory by finding the powershell.exe profile and adding `"startingDirectory": "%USERPROFILE%/Documents/GitHubRepos",`
 
 **Example with WSL:** When setting the starting directory for a [Linux distribution installed via WSL](/windows/wsl/install-win10), use the format: `"startingDirectory": "\\\\wsl$\\DISTRO NAME\\home\\USERNAME"`, replacing with the placeholders with the proper names of your distribution. For example, `"startingDirectory": "\\\\wsl$\\Ubuntu-20.04\\home\\user1"`. If you are using the Windows Terminal Settings UI, rather than the [settings.json file](../install.md#settings-json-file), to declare this path, you can use the **Browse...** button to select your starting directory or enter the WSL path as: `//wsl.localhost/DISTRO NAME/home/USERNAME`. For example, `//wsl.localhost/Ubuntu-20.04/home/user1`. 

TerminalDocs/customize-settings/themes.md

@@ -39,6 +39,15 @@ Each theme in the `themes` list is comprised of a collection of property objects
 },
 ```
 
+You may also configure the Terminal to use separate themes for light and dark mode in the OS and change automatically between those themes when the OS theme changes. To do this, specify the `theme` property as an object containing the keys `light` and `dark`:
+
+```json
+"theme": { "dark": "<Dark Theme Name>", "light": "<Light Theme Name>" },
+```
+
+> [!IMPORTANT]
+> Specifying a pair of `light` and `dark` themes is only available in [Windows Terminal Preview](https://aka.ms/terminal-preview).
+
 ## Theme name
 
 This is the name of the theme. Names should be unique. The names `dark`, `light`, and `system` are reserved for the built-in default themes.
@@ -55,6 +64,10 @@ ___
 
 ## Window
 
+These settings are used to configure the appearance of the whole of the window of the Terminal.
+
+**Property name:** `window`
+
 ### Application theme
 
 This sets the UI theme of the application. This will stylize items such as buttons, the command palette, and other application UI elements. It can either be light or dark. `"system"` will use the same theme as Windows.
@@ -69,12 +82,55 @@ This sets the UI theme of the application. This will stylize items such as butto
 
 <br />
 
+### Mica
+
+This enables the Mica effect on this window, beneath all other UI layers. For Mica to be visible, the layers above it need to be transparent. As an example, to have a tab row with Mica in it you'll need to configure the alpha channel of the background to be `0` as follows:
+
+```json
+{
+    "name": "My Mica Theme",
+    "tab":
+    {
+        "background": "terminalBackground"
+    },
+    "tabRow":
+    {
+        "background": "#00000000"
+    },
+    "window":
+    {
+        "applicationTheme": "system",
+        "useMica": true
+    }
+},
+```
+
+Note that when Mica is enabled for the window it is enabled under the entirety of the window, including as a backdrop for the Terminal panes in the window. This means that profiles which are using `opacity` without `useAcrylic` enabled will show through to the new Mica background. It is not currently possible to have a unblurred transparent background for the Terminal and a Mica background for the tabs / tab row simultaneously.
+
+**Property name:** `useMica`
+
+**Necessity:** Optional
+
+**Accepts:** `true`, `false`
+
+**Default value:** `false`
+
+> [!IMPORTANT]
+> Mica is only available in [Windows Terminal Preview](https://aka.ms/terminal-preview).
+
+> [!NOTE]
+> Mica is only available on Windows builds >= 22621.
+
+<br />
+
 ___
 
 ## Tab row
 
 These settings are used to configure the appearance of the tab row. When `showTabsInTitlebar` is `true` (the default), this configures the title bar.
 
+**Property name:** `tabRow`
+
 ### Background color
 
 The color of the tab row when the window is in the foreground.
@@ -101,6 +157,10 @@ ___
 
 ## Tabs
 
+These are settings that control the appearance of individual tabs in the Terminal.
+
+**Property name:** `tab`
+
 ### Background color
 
 The color of the active tab. Setting a `tabColor` in a profile will override this value. Similarly, setting a color at runtime with the tab color picker will override this color.

TerminalDocs/faq.yml

@@ -3,7 +3,7 @@ metadata:
   title: Windows Terminal FAQ
   description: Frequently asked questions about Windows Terminal, such as how to start terminal in administrator mode, how to save a terminal session, and more.
   ms.topic: faq
-  ms.date: 02/03/2022
+  ms.date: 03/10/2023
   ms.author: mattwoj
   author: mattwojo
   manager: jken
@@ -107,10 +107,42 @@ sections:
         answer: |
           No. For more technical details, refer to [this spec](https://github.com/microsoft/terminal/blob/main/doc/specs/%235000%20-%20Process%20Model%202.0/%231032%20-%20Elevation%20Quality%20of%20Life%20Improvements.md#background) and [this doc](https://github.com/microsoft/terminal/blob/main/doc/Niksa.md#elevation).
 
-      # - question: Is there a way to sync your terminal settings across devices?
-      #   answer: |
-      #     TBD
+      - question: Why is the Windows Terminal default appearance theme set to Dark, when my Windows operating system settings are set to Light?
+        answer: |
+          The system theme in Windows 11 defaults to the Light theme appearance unless changed by the user. Windows Terminal appearance color scheme, however, is Dark by default. Many users won't change the appearance themes and will just see the default themes. The goal of aligning Windows Terminal appearance with the colors of the Windows operating system (OS) titlebar leaves these options: 1) Do nothing (This is the Terminal default before v1.16). In the default setup, the result is a visually unappealing contrast between black terminal content with a light titlebar. 2) Default the color scheme of the terminal to match the OS theme and leave the app theme set to "system". In the default setup, this will result in the terminal appearing as black text on a white background. 3) Change the default theme of Windows Terminal to Dark, regardless of OS theme. In the default setup, this will result in the terminal appearing as white text on a black background, with a dark titlebar. Option 3 presented the optimum balance of the least surprise to users on the default settings, with the most aesthetically pleasing results. Windows Terminal v1.16 also introduced new toggles for customizing the appearance of the window, including: Customizing the title bar color, the tab color (including auto-matching the background), and enabling different colors for focused or unfocused windows. Windows Terminal 1.17 introduces additional flexibility with the ability to sync the Terminal theme to the OS theme and sync the color scheme to the OS theme. The Terminal is already 99% white text on a black background, these changes just line the title bar up with that.
+
+      - question: How do I change Windows Terminal theme back to "system"?
+        answer: |
+          Add `"theme": "system"` to your `settings.json`, or you can change the Theme on the "Appearance" page of the Windows Terminal Settings.
 
-      # - question: Can we expect a status bar on the bottom of Windows Terminal? 
-      #   answer: |
-      #     TBD
+      - question: Why is the tab still black after I set Windows Terminal to Light theme?
+        answer: |
+          This is a side effect of the Theme changes introduced in v1.16. The default themes in v1.16 and later will always use the Terminal background color as the default color for each tab. By default on a black terminal window, you will get a black tab. With a blue color scheme (like Campbell PowerShell), you'll get a blue tab. This is to give the Terminal a "seamless" feel. In Light mode, that creates a case where a black tab will appear on a white tab row. However, with v1.16 and later, you can customize the theme of the terminal. For example:
+          
+          ```json
+          "theme": "White Tabs",
+          "themes":
+          [
+              {
+                  "name": "White Tabs",
+                  "tab":
+                  {
+                      "background": "#ffffffff",
+                  },
+                  "window":
+                  {
+                      "applicationTheme": "light"
+                  }
+              },
+          ]
+          ```
+
+          Alternatively, if you're using an OS Light theme and want to set the terminal color scheme to a white background, v1.17 enables setting different color schemes based on the theme of the window. For example, to change the background color based on the `window.applicationTheme` of Windows Terminal, you can do this:
+
+          ```json
+          "colorScheme":
+          {
+              "light": "One Half Light",
+              "dark": "One Half Dark",
+          },
+          ```