Add spec for adding commandline arguments to wt.exe

[zadjii-msft]

Summary of the Pull Request

This is the first draft of a spec for adding commandline arguments to the Windows Terminal. This includes design work for a powerful future version of the commandline args for the Terminal, as well as a way that system could be implemented during 1.0 to provide basic functionality, while creating commadlines that will work without modification in (a future Windows Terminal version).

References

Referenced in the course of this spec:

• Feature Request: wt.exe supports command line arguments (profile, command, directory, etc.) #607 Feature Request: wt.exe supports command line arguments (profile, command, directory, etc.)
• Add "open Windows terminal here" into right-click context menu #1060 Add "open Windows terminal here" into right-click context menu
• Feature Request: Task Bar jumplist should show items from profile #576 Feature Request: Task Bar jumplist should show items from profile
• Draft spec for adding profiles to the Windows jumplist #1357 Draft spec for adding profiles to the Windows jumplist
• Spec for tab tear off and default app #2080 Spec for tab tear off and default app
• [Question] Configuring Windows Terminal profile to always launch elevated #632 [Question] Configuring Windows Terminal profile to always launch elevated
• Create new window key binding #2068 New window key binding not working

PR Checklist

• Specs Feature Request: wt.exe supports command line arguments (profile, command, directory, etc.) #607
• I work here
• it's a spec

Detailed Description of the Pull Request / Additional comments

Read the spec.

This is CURRENTLY a draft. I'm looking for feedback in this step before finishing it. There's not currently any implementation details, because I'd like feedback on the proposal before moving forward.

[DHowett-MSFT]

Should there be a broad unification of parameter names and command names (for bound commands)? Should one be able to pass any argument that a keybinding could take as a --argument?

[zadjii-msft]

Should there be a broad unification of parameter names and command names (for bound commands)? Should one be able to pass any argument that a keybinding could take as a --argument?

@DHowett-MSFT probably. I wasn't sure how far to take that - should someone be able to wt -d c:\foo ; duplicate-tab? What about wt -d c:\foo ; increase-font-size? I figured that we'd have a subset of ShortcutActions available as commands in the commandline, but those that have analogs should probably be an exact match (with a camelCase -> kebab-case translation)

In general though, it kinda makes sense to have the parameters for commands to be exact matches to the arguments to the similar ShortcutAction.

[miniksa]

I think you should call out that you seem to expressly be avoiding somehow delimiting the arguments on the command line to make life easier for folks who are launching something with arguments. Mismatching 500 escaping mechanisms is the bane of our existence for things like "launching an executable through cmd through powershell through tshell to a device". At least, that was my understanding as to why you didn't have a --arguments "foo arguments" option after the command line for a launch.

[ExE-Boss]

PowerShell uses ; as command separators, so:

wt new-tab cmd.exe ; split-pane -P 30 wsl.exe

Means:

1. Run wt(.exe) with ['new-tab', 'cmd.exe'] as the arguments.
2. Run split-pane(.exe) with ['-P', '30', 'wsl.exe'] as the arguments.
   • This will throw an exception, unless the user has a split‑pane command on their PATH or as a PowerShell cmdlet 

[zadjii-msft]

@ExE-Boss thanks for the breakdown. Clearly, I'm more of a cmd guy 😅.

I've added more details in this section to elaborate upon this point. Let's use this thread to discuss. Technically, we could ask the user to escape our commandline in powershell, like wt new-tab `; new-pane commandline \`; with \`; semicolons or wt new-tab ';' new-pane "commandline \; with \; semicolons". However, if the party line is "use powershell", does it really make sense for us to add a commandline that fundamentally needs to be escaped when running in powershell? What other command separators could we use?

[carlos-zamora]

--?

[carlos-zamora]

I'm all for this, but is there a value to getting the guids?

[zadjii-msft]

Maybe? I guess I really just threw this out there as a proposal. GUIDs are going to be more stable than names, at least as far as scripting is concerned. But you're right that this probably doesn't add real value.

[cinnamon-msft]

I thought the same thing. Not sure if it adds much value.

[carlos-zamora]

will we ever consider this to go beyond % units? Like maybe accept 0.5?

[zadjii-msft]

Yea probably. I figured 50.5 and other decimal values would already be reasonable params here. I was thinking in the future we might also have a --size,-s arg, which specifies the size in number of chars. Though, that one's a little trickier, because it's hard for the shell to know what size in characters the terminal has available to it, you know?

[carlos-zamora]

Any reason why we're not just adding all of the profile settings here? Like acrylicOpacity, color scheme, etc...

[zadjii-msft]

Honestly there's not a good reason. It probably could have all the settings, I just started somewhere. I'll make a patch with all the settings to see what that looks like.

[qqkookie]

How about option to set tab title label? Currently WT tab with "cmd" and "Power Shell" profile have fixed tab title (from the profile "name" attribute) and taskbar label. It would be nice to have command line option can set the active tab title. This also will set name on the taskbar. For example, --title "This is tab title" will override the default Window name like "cmd". It will help to identify multiple instance of WT windows in the taskbar.

And with same reason, we need new profile attribute in "setting.json" for the tab title ("Title: "This is title" in profile entry) , separate from the profile "name" (default tab title). so that the WT windows tab may have short profile name and longer and more descriptive tab title, different from the profile name. It will be used as default title when no --title option is specified on the command line.

And on --startingDirectory option: how about accepting "~" notation of unix shell for %USERPROFILE%? i.e --startingDirectory "~" will be same as --startingDirectory "%USERPROFILE%".

And if --startingDirectory has no argument, then use current directory inherited form invoking process. i.e. ignoring "startingDirector" attribute in the profile (in setting.json). --startingDirectory alone will be same as --startingDirectory "."

And if --StartingDiretory option is used, then simple lone --title option (with no argument) will set the tab title from the StartingDirectory value. Only last path component name is used to limit length of title and taskbar label. If Both --StartingDiretory and --title option has no argument, then get current directory and use last path component of current directory.

For example, --StartingDirectory "~\Desktop\ProjectA" --title is resolved as --StartingDirectory "C:\Users\JohnDoe\Desktop\ProjectA" --title "ProjectA" , then only "ProjectA" part is used as tab title, not full path.

[miniksa]

eh

[miniksa]

Gave it another pass. Are we planning on committing this soon? There's not a lot of commentary left. I'm going to approve it as is as it's close enough to a reasonable plan to me.

[zadjii-msft]

@miniksa I'd love to get this merged soon 😄 With the holidays over, I'm hoping it'll be easier to get another 2 signoffs to get this spec merged next week

[DHowett-MSFT]

In favor of "implicit new-tab": wt.exe without any arguments is already an implicit new-window or new-tab; we can't claw back the implicitness and ease of use in that one, so I think in the spirit of keeping that going WT should automatically do anything necessary to service a command (wt split-pane should operate in a new tab or new window, etc.)

[miniksa]

In favor of "implicit new-tab": wt.exe without any arguments is already an implicit new-window or new-tab; we can't claw back the implicitness and ease of use in that one, so I think in the spirit of keeping that going WT should automatically do anything necessary to service a command (wt split-pane should operate in a new tab or new window, etc.)

ACK that @DHowett-MSFT won me over in our triage today with this argument and I stand down from my earlier position.

[DHowett-MSFT]

Should we need a -r option ("remote") to say "control a windows terminal instance?" with autodetection for the one it's running in? hmm

[jantari]

I still don't like the ; syntax for specifying more complex (e.g. multi-pane) start configurations.

What if we could pass JSON as an argument instead?

I don't have a full spec for this but:

1. It would allow passing arbitrarily complex configurations in a structured manner
2. It would be trivial to escape/use from PowerShell as JSON does not contain the ' character, which PowerShell uses to denote verbatim/literal strings.
3. Possibly large chuncks of the existing JSON settings parser could be re-used to parse the command line. Invalid syntax or configurations are easy to detect by the JSON parser.

Examples to illustrate the idea:

wt.exe --profile "Windows Powershell"
# could become:
wt.exe {"profile":"Windows PowerShell"}
# or in PowerShell:
wt.exe '{"profile":"Windows PowerShell"}'

wt.exe cmd.exe ; split-pane --target-pane 0 -v -% 30 wsl.exe
# could become:
wt.exe {"tabs":[{"panes":[{"profile":"cmd","size":"70%","vertical":true},{"executable":"wsl.exe"}]}]}
# or in PowerShell, simply:
wt.exe '{"tabs":[{"panes":[{"profile":"cmd","size":"70%","vertical":true},{"executable":"wsl.exe"}]}]}'

# The JSON expanded is this:
{
  "tabs": [
    {
      "panes": [
        {
          "profile": "cmd",
          "size": "70%",
          "vertical": true
        },
        {
          "executable": "wsl.exe"
        }
      ]
    }
  ]
}

If the existing JSON settings parser is re-used, arbitary settings-values could be overwritten/specified on the command line:

{
  "tabs": [
    {
      "panes": [
        {
          "profile": "cmd",
          "size": "70%",
          "vertical": true,
          "startingDirectory":  "%USERPROFILE%",
          "tabTitle":  "my funny tab 123",
          "useAcrylic":  false
        },
        {
          "executable": "wsl.exe"
        }
      ]
    }
  ]
}

Because command-line commands in CMD.EXE can only be 1024 characters long (forgot source, possibly no longer the case?) this would provide an easy path to specify a JSON-configuration in a file for SUPER DUPER intricate setups, e.g. wt.exe --launchconfig ubersetup.json

In fairness, I want to mention that PowerShell has the --% (stop parsing) operator, which instructs it to stop interpreting anything after it and just pass it on verbatim. So, the semicolon-problem could also be addressed by the following syntax:

# wt.exe still needs to be interpreted by PowerShell as it's a command in PATH, but nothing after it
wt.exe --% cmd.exe ; split-pane --target-pane 0 -v -% 30 wsl.exe

Still, it's a highly ugly and "proprietary" syntax, e.g. yet another thing to learn/go wrong. JSON is well understood both from the user and the dev side.

[DHowett-MSFT]

Still, it's a highly ugly and "proprietary" syntax, e.g. yet another thing to learn/go wrong. JSON is well understood both from the user and the dev side.

I dunno about this one. We're trying to bridge the gap between user-friendliness (which typing a blob of JSON does not have) and machine parseability. It seems like tmux is already using ; as a separator (see the manual, section PARSING SYNTAX), so this is not proprietary.

Ugliness, however, is in the eye of the beholder. Passing a commandline filled with fully syntactically-correct JSON is subjectively uglier to me than "wt action args ; action args ; action args".

[carlos-zamora]

In fairness, I want to mention that PowerShell has the --% (stop parsing) operator, which instructs it to stop interpreting anything after it and just pass it on verbatim. So, the semicolon-problem could also be addressed by the following syntax:

# wt.exe still needs to be interpreted by PowerShell as it's a command in PATH, but nothing after it
wt.exe --% cmd.exe ; split-pane --target-pane 0 -v -% 30 wsl.exe

@zadjii-msft can we add this to the spec? Specifically where you talk about escaping the semicolons in powershell. This alleviates my main concern.

[jawn]

Add period to end of sentence.