diff --git a/TerminalDocs/command-line-arguments.md b/TerminalDocs/command-line-arguments.md index 67372893..bfb2513d 100644 --- a/TerminalDocs/command-line-arguments.md +++ b/TerminalDocs/command-line-arguments.md @@ -25,6 +25,14 @@ wt [options] [command ; ] > [!NOTE] > The [`windowingBehavior` property](./customize-settings/startup.md#new-instance-behavior) can affect the behavior of the `wt.exe` command. Adjust this setting to default between opening a new window or opening a new tab. +> [!IMPORTANT] +> If you have enabled the **"Open windows from a previous session"** startup option ([`firstWindowPreference: "persistedWindowLayout"`](./customize-settings/startup.md#behavior-when-starting-a-new-terminal-session)), running `wt` from the command line will restore your previous session **and** execute the command you provided, potentially opening two windows. To prevent this behavior, use the `--window, -w` option to control where your command executes: +> - `wt -w 0 nt -p ` - Opens in the most recently used window (prevents a second window from opening) +> - `wt -w -1 nt -p ` - Forces a new window without restoring the previous session +> - `wt -w nt -p ` - Opens in a named window, creating it only if it doesn't exist +> +> See the [`--window` option](#options-and-commands) below for more details. + To display a help message that lists the available command line arguments, enter: `wt -h`, `wt --help`, `wt -?`, or `wt /?`. ## Options and commands @@ -214,6 +222,57 @@ Execution aliases don't work in WSL distributions. If you want to use wt.exe fro --- +### Session restore and command line arguments + +If you have enabled the **"Open windows from a previous session"** startup option ([`firstWindowPreference: "persistedWindowLayout"`](./customize-settings/startup.md#behavior-when-starting-a-new-terminal-session)), running `wt` with command line arguments will both restore your previous session layout **and** execute your command, which may result in opening two windows. + +To avoid this behavior when session restore is enabled, use the `--window, -w` option to control where your commands execute: + + +#### [Command Prompt](#tab/windows) + +```cmd +// Open a new tab with a specific profile in the most recently used window (avoids opening a second window) +wt -w 0 nt -p "Ubuntu-18.04" + +// Force a new window with the profile, without restoring previous session +wt -w -1 nt -p "Command Prompt" + +// Open in a named window (creates it only if it doesn't exist) +wt -w mywork nt -p "PowerShell" +``` + +#### [PowerShell](#tab/powershell) + +```powershell +// Open a new tab with a specific profile in the most recently used window (avoids opening a second window) +wt -w 0 nt -p "Ubuntu-18.04" + +// Force a new window with the profile, without restoring previous session +wt -w -1 nt -p "Command Prompt" + +// Open in a named window (creates it only if it doesn't exist) +wt -w mywork nt -p "PowerShell" +``` + +#### [Linux](#tab/linux) + +```bash +// Open a new tab with a specific profile in the most recently used window (avoids opening a second window) +cmd.exe /c "wt.exe" -w 0 nt -p "Ubuntu-18.04" + +// Force a new window with the profile, without restoring previous session +cmd.exe /c "wt.exe" -w -1 nt -p "Command Prompt" + +// Open in a named window (creates it only if it doesn't exist) +cmd.exe /c "wt.exe" -w mywork nt -p "PowerShell" +``` + +Execution aliases don't work in WSL distributions. If you want to use wt.exe from a WSL command line, you can spawn it from CMD directly by running `cmd.exe`. The `/c` option tells CMD to terminate after running. + +--- + + ### Open a new profile instance To open a new terminal instance, such as the profile named "Ubuntu-18.04", enter: