Docs for elevate

TerminalDocs/customize-settings/actions.md

@@ -403,6 +403,10 @@ This creates a new tab. Without any arguments, this will open the default profil
 | `profile` | Optional | Profile's name or GUID as a string | Profile that will open based on its GUID or name. |
 | `colorScheme` | Optional | The name of a color scheme as a string | The scheme to use instead of the profile's set `colorScheme` |
 | `suppressApplicationTitle` | Optional | `true`, `false` | When set to `false`, applications can change the tab title by sending title change messages. When set to `true`, these messages are suppressed. If not provided, the behavior is inherited from the profile's settings. In order to enter a new tab title and have that title persist, this must be set to true. |
+| `elevate` | Optional | `true`, `false` | Overrides the [`elevate`](./profile-general.md#automatically-run-as-administrator) property of the profile. When omitted, this action will behave according to the profile's `elevate` setting. When set to `true` or `false`, this action will behave as though the profile was maked `"elevate": true` or `"elevate": false` (respectively) |
+
+> [!IMPORTANT]
+> The `"elevate"` property is only available in [Windows Terminal Preview](https://aka.ms/terminal-preview).
 
 ### Open next tab
 
@@ -803,10 +807,14 @@ This halves the size of the active pane and opens another. Without any arguments
 | `suppressApplicationTitle` | Optional | `true`, `false` | When set to `false`, applications can change the tab title by sending title change messages. When set to `true`, these messages are suppressed. If not provided, the behavior is inherited from the profile's settings. |
 | `splitMode` | Optional | `"duplicate"` | Controls how the pane splits. Only accepts `"duplicate"`, which will duplicate the focused pane's profile into a new pane. |
 | `size` | Optional | Float | Specify how large the new pane should be, as a fraction of the current pane's size. `1.0` would be "all of the current pane", and `0.0` is "None of the parent". Defaults to `0.5`. |
+| `elevate` | Optional | `true`, `false` | Overrides the [`elevate`](./profile-general.md#automatically-run-as-administrator) property of the profile. When omitted, this action will behave according to the profile's `elevate` setting. When set to `true` or `false`, this action will behave as though the profile was maked `"elevate": true` or `"elevate": false` (respectively) |
 
 > [!IMPORTANT]
 > The `"up"`, `"right"`, `"down"`, and `"left"` options for `split` are only available in [Windows Terminal Preview](https://aka.ms/terminal-preview).
 
+> [!IMPORTANT]
+> The `"elevate"` property is only available in [Windows Terminal Preview](https://aka.ms/terminal-preview).
+
 <br />
 
 ___

TerminalDocs/customize-settings/profile-general.md

@@ -105,7 +105,32 @@ If set, this will replace the `name` as the title to pass to the shell on startu
 **Accepts:** String
 
 <br />
+___
+
+## Automatically run as administrator
+
+If set, this profile will automatically open up in an "elevated" window (running as administrator) by default. If you run this profile from an unelevated window, then a new elevated terminal window will be created to host this profile. If you launch this profile from an already elevated window, then it will open as a new tab.
+
+When this property is set to `false`, opening this profile in an elevated window will not launch an _unelevated_ window to host this profile. The profile will simply open in the elevated window, running as admin.
+
+If you set this property in `profiles.defaults`, then _all_ profiles will launch as administrator by default, unless overrided by specifically setting this to false.
+
+This property can be overridden in the [`newTab`](./actions.md#new-tab) and [`splitPane`](./actions.md#split-a-pane) actions, with the `elevate` property.
+
+Elevated and unelevated tabs cannot exist in the same Terminal window. For more details, please see the [FAQ](/faq.yml#can-you-have-have-tabs-running-as-administrator--elevated--in-unelevated-terminal-windows).
+
+**Property name:** `elevate`
 
+**Necessity:** Optional
+
+**Accepts:** `true`, `false`
+
+**Default value:** `false`
+
+> [!IMPORTANT]
+> This feature is only available in [Windows Terminal Preview](https://aka.ms/terminal-preview).
+
+<br />
 ___
 
 ## Hide profile from dropdown

TerminalDocs/faq.yml

@@ -100,6 +100,10 @@ sections:
         answer: |
          The PSReadLine module is responsible for setting the colors and behavior of your PowerShell command line. You can set colors for specific attributes of your PowerShell prompt by using the [Set-PSReadLineOption, see Example 4: Set multiple color options](/powershell/module/psreadline/set-psreadlineoption#example-4--set-multiple-color-options).
 
+      - question: Can you have have tabs running as Administrator (elevated) in unelevated Terminal windows?
+        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