Implement wtcli, an application to query details about an existing Terminal instance

.github/actions/spelling/allow/allow.txt

@@ -21,6 +21,7 @@ downsides
 Emacspeak
 Fitt
 flac
+focusp
 FTCS
 gantt
 gfm
@@ -32,20 +33,24 @@ https
 hyperlinking
 hyperlinks
 Kbds
+killp
 libfuzzer
 liga
 Llast
 LLMs
 Lmid
 locl
 lol
+lsp
+lsw
 Lorigin
 maxed
 megathread
 minimalistic
 mkmk
 mnt
 mru
+newt
 notwrapped
 NPCs
 NTMTo
@@ -72,8 +77,10 @@ rubyw
 runtimes
 servicebus
 slnt
+splitp
 ssh
 stakeholders
+submittable
 subpage
 subpages
 sustainability

.github/actions/spelling/allow/apis.txt

@@ -17,9 +17,11 @@ CLOSEAPP
 cmdletbinding
 colspan
 COMDLG
+combase
 commandlinetoargv
 COPYFROMRESOURCE
 cstdint
+CWin
 CXICON
 CYICON
 dataobject
@@ -80,6 +82,7 @@ lsass
 LSHIFT
 LTGRAY
 MAINWINDOW
+MBM
 medi
 memicmp
 MENUCOMMAND
@@ -200,6 +203,8 @@ winstamin
 wmemcmp
 wpc
 WSF
+wtcli
+wtdcli
 WWH
 wwinmain
 XDocument

.github/actions/spelling/allow/names.txt

@@ -5,6 +5,7 @@ bhoj
 Bhojwani
 Bluloco
 carlos
+DFX
 dhowett
 Diviness
 dsafa
@@ -59,6 +60,7 @@ Thysell
 WDX
 Wellons
 Westerman
+yeelam
 zadjii
 Zamor
 zamora

OpenConsole.slnx

@@ -449,6 +449,7 @@
   <Folder Name="/Terminal/">
     <Project Path="src/cascadia/CascadiaPackage/CascadiaPackage.wapproj" Type="c7167f0d-bc9f-4e6e-afe1-012c56b48db5">
       <BuildDependency Project="src/cascadia/ShellExtension/WindowsTerminalShellExt.vcxproj" />
+      <BuildDependency Project="src/tools/wtcli/wtcli.vcxproj" />
       <BuildType Solution="AuditMode|Any CPU" Project="Debug" />
       <BuildType Solution="AuditMode|ARM64" Project="Release" />
       <BuildType Solution="AuditMode|x64" Project="Release" />
@@ -1046,4 +1047,15 @@
       <Build Solution="Fuzzing|x86" Project="false" />
     </Project>
   </Folder>
+  <Project Path="src/tools/wtcli/wtcli.vcxproj" Id="8a3b5e2f-1c4d-4f6a-9b8c-0d1e2f3a4b5c" />
+  <Project Path="src/cascadia/TerminalProtocol/TerminalProtocol.vcxproj" Id="f1a2b3c4-d5e6-4f7a-8b9c-0d1e2f3a4b5d" />
+  <Project Path="src/cascadia/TerminalProtocol/ft_fuzzer/ProtocolFuzzer.vcxproj" Id="26711d2f-ca10-45be-9e89-43771030bdb0">
+    <Platform Solution="*|Any CPU" Project="Win32" />
+    <Build Solution="*|Any CPU" Project="false" />
+    <Build Solution="*|ARM64" Project="false" />
+    <Build Solution="*|x86" Project="false" />
+    <Build Solution="AuditMode|x64" Project="false" />
+    <Build Solution="Debug|x64" Project="false" />
+    <Build Solution="Release|x64" Project="false" />
+  </Project>
 </Solution>

doc/wtcli-commands.md

@@ -0,0 +1,64 @@
+# wtcli Command Reference
+
+`wtcli` is the CLI client for the Windows Terminal Protocol. It calls
+`CoCreateInstance` using the per-brand `CLSID` and exposes a tmux-style command surface over its IDL methods.
+
+- Source: `src/tools/wtcli/main.cpp`
+- IDL: `src/host/proxy/ITerminalProtocol.idl`
+
+## Global flags
+
+| Flag | Effect |
+|------|--------|
+| `--json` | Emit machine-readable JSON. Required for any caller that parses output. |
+
+## Commands
+
+| Command | Alias | What it does | Example |
+|---------|-------|--------------|---------|
+| `list-windows` | `lsw` | List all Terminal windows, with each window's `name` and `title`. | `wtcli --json list-windows` |
+| `list-tabs` | `lst` | List tabs in a window. `-w` picks the window (default: current); `--all` lists every window's tabs. | `wtcli --json list-tabs -w build` |
+| `list-panes` | `lsp` | List panes in a tab. `-w` picks the window (default: current), `-t` the tab (default: its first); `--all` lists every pane in every window. | `wtcli --json list-panes -t 2` |
+| `active-pane` |  | Return metadata for the currently focused pane. Used by other subcommands as the default `-t` target. | `wtcli --json active-pane` |
+| `pane-status` |  | Report pane process state: `pid`, `state` (`running`/`exited`), and `exit_code` when applicable. | `wtcli --json pane-status -t 3` |
+| `new-tab` | `newt` | Create a new tab. `-c` command, `-n` title, `-d` cwd, `-w` window (default: current). Unlike the read-only commands, `-w` here may create the window. | `wtcli --json new-tab -c "pwsh" -n "build" -d C:\src` |
+| `split-pane` | `splitp` | Split a pane. `-d right\|left\|up\|down\|auto` (default `automatic`). `-H`/`-v` are legacy aliases for `down`/`right`. `-s` is size fraction; `-c` is the command to run. | `wtcli --json split-pane -t 3 -d right -s 0.4 -c "tail -f log"` |
+| `kill-pane` | `killp` | Close a pane. | `wtcli kill-pane -t 4` |
+| `focus-pane` | `focusp` | Move focus to the given pane. | `wtcli focus-pane -t 3` |
+
+## Targeting a window with `-w`
+
+`-w,--window` uses the same grammar as `wt --window,-w` (they both go through the
+same parser: `src/cascadia/WindowsTerminal/WindowTarget.h`)
+
+| `-w` value | Means |
+|------------|-------|
+| *(omitted)* | The current window. |
+| `0`, `last` | The current window. |
+| a positive integer | The window with that `window_id`, as reported by `list-windows`. |
+| `new`, or a negative integer | A new window. |
+| anything else | The window with that **name**, as reported by `list-windows`. |
+
+
+### Creating windows with `new-tab`
+
+`wtcli new-tab -w new` and `wtcli new-tab -w <unused-name>` create the window
+and make the requested tab its first tab.
+
+A new window builds that tab asynchronously, so by default the server waits up
+to 10s for it and then reports the usual `session_id`/`pid`. Pass `--no-wait` to
+return as soon as the window exists. Either way, if the tab isn't ready the
+result is still a success, flagged with `"pending": true`:
+
+```console
+$ wtcli --json new-tab -w new --no-wait
+{"pending":true,"pid":0,"session_id":"{00000000-0000-0000-0000-000000000000}","tab_id":0,"window_id":4}
+```
+
+When `pending` is true, only `window_id` is meaningful. Follow up with
+`wtcli --json list-panes -w <window_id>` once the window has started. Scripts
+should branch on `pending` rather than testing `session_id` for emptiness.
+
+Targeting a name that has a **saved workspace** restores that workspace, and the
+requested tab is dropped, because a persisted layout takes precedence over requested
+startup actions. This matches `wt -w <name>`.

src/cascadia/CascadiaPackage/CascadiaPackage.wapproj

@@ -18,6 +18,8 @@
     <AppxOSMaxVersionTestedReplaceManifestVersion>false</AppxOSMaxVersionTestedReplaceManifestVersion>
     <OCExecutionAliasName Condition="'$(WindowsTerminalBranding)'=='' or '$(WindowsTerminalBranding)'=='Dev'">wtd</OCExecutionAliasName>
     <OCExecutionAliasName Condition="'$(OCExecutionAliasName)'==''">wt</OCExecutionAliasName>
+    <OCCliExecutionAliasName Condition="'$(WindowsTerminalBranding)'=='' or '$(WindowsTerminalBranding)'=='Dev'">wtdcli</OCCliExecutionAliasName>
+    <OCCliExecutionAliasName Condition="'$(OCCliExecutionAliasName)'==''">wtcli</OCCliExecutionAliasName>
   </PropertyGroup>
   <PropertyGroup>
     <ProjectGuid>CA5CAD1A-224A-4171-B13A-F16E576FDD12</ProjectGuid>
@@ -92,6 +94,9 @@
     <ProjectReference Include="$(OpenConsoleDir)src\host\proxy\Host.Proxy.vcxproj">
       <Project>{71CC9D78-BA29-4D93-946F-BEF5D9A3A6EF}</Project>
     </ProjectReference>
+    <ProjectReference Include="$(OpenConsoleDir)src\tools\wtcli\wtcli.vcxproj">
+      <Project>{8A3B5E2F-1C4D-4F6A-9B8C-0D1E2F3A4B5C}</Project>
+    </ProjectReference>
   </ItemGroup>
 
   <Target Name="OpenConsoleStompSourceProjectForWapProject" BeforeTargets="_ConvertItems">
@@ -105,6 +110,7 @@
         </SourceProject>
         <!-- Replace the filename for wt/wtd.exe with the one that the manifest wants. -->
         <TargetPath Condition="'%(Filename)' == 'wt' and '%(Extension)' == '.exe'">$(OCExecutionAliasName).exe</TargetPath>
+        <TargetPath Condition="'%(Filename)' == 'wtcli' and '%(Extension)' == '.exe'">$(OCCliExecutionAliasName).exe</TargetPath>
       </_FilteredNonWapProjProjectOutput>
     </ItemGroup>
   </Target>

src/cascadia/CascadiaPackage/Package-Can.appxmanifest

@@ -113,6 +113,7 @@
                 <com:Interface Id="E686C757-9A35-4A1C-B3CE-0BCC8B5C69F4" ProxyStubClsid="1D1852F4-ADAD-42B6-9A43-9437AAAD7717"/>
                 <com:Interface Id="6F23DA90-15C5-4203-9DB0-64E73F1B1B00" ProxyStubClsid="1D1852F4-ADAD-42B6-9A43-9437AAAD7717"/> <!-- ITerminalHandoff3 -->
                 <com:Interface Id="746E6BC0-AB05-4E38-AB14-71E86763141F" ProxyStubClsid="1D1852F4-ADAD-42B6-9A43-9437AAAD7717"/>
+                <com:Interface Id="D999831E-7EBD-4B14-9D2F-8B09417582D4" ProxyStubClsid="1D1852F4-ADAD-42B6-9A43-9437AAAD7717"/> <!-- ITerminalProtocol -->
             </com:ComInterface>
         </com:Extension>
         <com:Extension Category="windows.comServer">
@@ -122,6 +123,7 @@
                 </com:ExeServer>
                 <com:ExeServer DisplayName="WindowsTerminal" Executable="WindowsTerminal.exe">
                     <com:Class Id="1706609C-A4CE-4C0D-B7D2-C19BF66398A5"/>
+                    <com:Class Id="264DE65B-F597-4183-8A76-6A039A604725"/> <!-- TerminalProtocolComServer (Canary) -->
                 </com:ExeServer>
                 <com:SurrogateServer DisplayName="WindowsTerminalShellExt">
                     <com:Class Id="6119575F-6918-4392-AF16-C2C627AF9416" Path="WindowsTerminalShellExt.dll" ThreadingModel="STA"/>
@@ -142,6 +144,25 @@
       </Extensions>
 
     </Application>
+
+    <Application Id="WtCli"
+      Executable="wtcli.exe"
+      EntryPoint="Windows.FullTrustApplication">
+      <uap:VisualElements
+        DisplayName="ms-resource:AppNameCan"
+        Description="ms-resource:AppDescriptionCan"
+        BackgroundColor="transparent"
+        Square150x150Logo="Images\Square150x150Logo.png"
+        Square44x44Logo="Images\Square44x44Logo.png"
+        AppListEntry="none" />
+      <Extensions>
+        <uap3:Extension Category="windows.appExecutionAlias" Executable="wtcli.exe" EntryPoint="Windows.FullTrustApplication">
+          <uap3:AppExecutionAlias>
+            <desktop:ExecutionAlias Alias="wtcli.exe" />
+          </uap3:AppExecutionAlias>
+        </uap3:Extension>
+      </Extensions>
+    </Application>
   </Applications>
 
   <Capabilities>

src/cascadia/CascadiaPackage/Package-Dev.appxmanifest

@@ -113,6 +113,7 @@
                 <com:Interface Id="E686C757-9A35-4A1C-B3CE-0BCC8B5C69F4" ProxyStubClsid="DEC4804D-56D1-4F73-9FBE-6828E7C85C56"/>
                 <com:Interface Id="6F23DA90-15C5-4203-9DB0-64E73F1B1B00" ProxyStubClsid="DEC4804D-56D1-4F73-9FBE-6828E7C85C56"/> <!-- ITerminalHandoff3 -->
                 <com:Interface Id="746E6BC0-AB05-4E38-AB14-71E86763141F" ProxyStubClsid="DEC4804D-56D1-4F73-9FBE-6828E7C85C56"/>
+                <com:Interface Id="D999831E-7EBD-4B14-9D2F-8B09417582D4" ProxyStubClsid="DEC4804D-56D1-4F73-9FBE-6828E7C85C56"/> <!-- ITerminalProtocol -->
             </com:ComInterface>
         </com:Extension>
         <com:Extension Category="windows.comServer">
@@ -122,6 +123,7 @@
                 </com:ExeServer>
                 <com:ExeServer DisplayName="WindowsTerminal" Executable="WindowsTerminal.exe">
                     <com:Class Id="051F34EE-C1FD-4B19-AF75-9BA54648434C"/>
+                    <com:Class Id="AD9425AA-1722-4E7B-A451-AA1D09106E83"/> <!-- TerminalProtocolComServer (Dev) -->
                 </com:ExeServer>
                 <com:SurrogateServer DisplayName="WindowsTerminalShellExt">
                     <com:Class Id="52065414-e077-47ec-a3ac-1cc5455e1b54" Path="WindowsTerminalShellExt.dll" ThreadingModel="STA"/>
@@ -142,6 +144,25 @@
       </Extensions>
 
     </Application>
+
+    <Application Id="WtCli"
+      Executable="wtdcli.exe"
+      EntryPoint="Windows.FullTrustApplication">
+      <uap:VisualElements
+        DisplayName="ms-resource:AppNameDev"
+        Description="ms-resource:AppDescriptionDev"
+        BackgroundColor="transparent"
+        Square150x150Logo="Images\Square150x150Logo.png"
+        Square44x44Logo="Images\Square44x44Logo.png"
+        AppListEntry="none" />
+      <Extensions>
+        <uap3:Extension Category="windows.appExecutionAlias" Executable="wtdcli.exe" EntryPoint="Windows.FullTrustApplication">
+          <uap3:AppExecutionAlias>
+            <desktop:ExecutionAlias Alias="wtdcli.exe" />
+          </uap3:AppExecutionAlias>
+        </uap3:Extension>
+      </Extensions>
+    </Application>
   </Applications>
 
   <Capabilities>

src/cascadia/CascadiaPackage/Package-Pre.appxmanifest

@@ -202,6 +202,7 @@
                 <com:Interface Id="E686C757-9A35-4A1C-B3CE-0BCC8B5C69F4" ProxyStubClsid="1833E661-CC81-4DD0-87C6-C2F74BD39EFA"/>
                 <com:Interface Id="6F23DA90-15C5-4203-9DB0-64E73F1B1B00" ProxyStubClsid="1833E661-CC81-4DD0-87C6-C2F74BD39EFA"/> <!-- ITerminalHandoff3 -->
                 <com:Interface Id="746E6BC0-AB05-4E38-AB14-71E86763141F" ProxyStubClsid="1833E661-CC81-4DD0-87C6-C2F74BD39EFA"/>
+                <com:Interface Id="D999831E-7EBD-4B14-9D2F-8B09417582D4" ProxyStubClsid="1833E661-CC81-4DD0-87C6-C2F74BD39EFA"/> <!-- ITerminalProtocol -->
             </com:ComInterface>
         </com:Extension>
         <com:Extension Category="windows.comServer">
@@ -211,6 +212,7 @@
                 </com:ExeServer>
                 <com:ExeServer DisplayName="WindowsTerminal" Executable="WindowsTerminal.exe">
                     <com:Class Id="86633F1F-6454-40EC-89CE-DA4EBA977EE2"/>
+                    <com:Class Id="D77C8A1A-83C0-42FC-BADF-9BE82E2A1624"/> <!-- TerminalProtocolComServer (Preview) -->
                 </com:ExeServer>
                 <com:SurrogateServer DisplayName="WindowsTerminalShellExt">
                     <com:Class Id="02db545a-3e20-46de-83a5-1329b1e88b6b" Path="WindowsTerminalShellExt.dll" ThreadingModel="STA"/>
@@ -231,6 +233,25 @@
       </Extensions>
 
     </Application>
+
+    <Application Id="WtCli"
+      Executable="wtcli.exe"
+      EntryPoint="Windows.FullTrustApplication">
+      <uap:VisualElements
+        DisplayName="ms-resource:AppNamePre"
+        Description="ms-resource:AppDescriptionPre"
+        BackgroundColor="transparent"
+        Square150x150Logo="Images\Square150x150Logo.png"
+        Square44x44Logo="Images\Square44x44Logo.png"
+        AppListEntry="none" />
+      <Extensions>
+        <uap3:Extension Category="windows.appExecutionAlias" Executable="wtcli.exe" EntryPoint="Windows.FullTrustApplication">
+          <uap3:AppExecutionAlias>
+            <desktop:ExecutionAlias Alias="wtcli.exe" />
+          </uap3:AppExecutionAlias>
+        </uap3:Extension>
+      </Extensions>
+    </Application>
   </Applications>
 
   <Capabilities>

src/cascadia/CascadiaPackage/Package.appxmanifest

@@ -202,6 +202,7 @@
                 <com:Interface Id="E686C757-9A35-4A1C-B3CE-0BCC8B5C69F4" ProxyStubClsid="3171DE52-6EFA-4AEF-8A9F-D02BD67E7A4F"/>
                 <com:Interface Id="6F23DA90-15C5-4203-9DB0-64E73F1B1B00" ProxyStubClsid="3171DE52-6EFA-4AEF-8A9F-D02BD67E7A4F"/> <!-- ITerminalHandoff3 -->
                 <com:Interface Id="746E6BC0-AB05-4E38-AB14-71E86763141F" ProxyStubClsid="3171DE52-6EFA-4AEF-8A9F-D02BD67E7A4F"/>
+                <com:Interface Id="D999831E-7EBD-4B14-9D2F-8B09417582D4" ProxyStubClsid="3171DE52-6EFA-4AEF-8A9F-D02BD67E7A4F"/> <!-- ITerminalProtocol -->
             </com:ComInterface>
         </com:Extension>
         <com:Extension Category="windows.comServer">
@@ -211,6 +212,7 @@
                 </com:ExeServer>
                 <com:ExeServer DisplayName="WindowsTerminal" Executable="WindowsTerminal.exe">
                     <com:Class Id="E12CFF52-A866-4C77-9A90-F570A7AA2C6B"/>
+                    <com:Class Id="832FDEC7-AA6F-4BAB-85FA-A491405638FC"/> <!-- TerminalProtocolComServer (Release) -->
                 </com:ExeServer>
                 <com:SurrogateServer DisplayName="WindowsTerminalShellExt">
                     <com:Class Id="9f156763-7844-4dc4-b2b1-901f640f5155" Path="WindowsTerminalShellExt.dll" ThreadingModel="STA"/>
@@ -231,6 +233,25 @@
       </Extensions>
 
     </Application>
+
+    <Application Id="WtCli"
+      Executable="wtcli.exe"
+      EntryPoint="Windows.FullTrustApplication">
+      <uap:VisualElements
+        DisplayName="ms-resource:AppName"
+        Description="ms-resource:AppDescription"
+        BackgroundColor="transparent"
+        Square150x150Logo="Images\Square150x150Logo.png"
+        Square44x44Logo="Images\Square44x44Logo.png"
+        AppListEntry="none" />
+      <Extensions>
+        <uap3:Extension Category="windows.appExecutionAlias" Executable="wtcli.exe" EntryPoint="Windows.FullTrustApplication">
+          <uap3:AppExecutionAlias>
+            <desktop:ExecutionAlias Alias="wtcli.exe" />
+          </uap3:AppExecutionAlias>
+        </uap3:Extension>
+      </Extensions>
+    </Application>
   </Applications>
 
   <Capabilities>