Should we use namespacing in the CLI

[Tyriar]

@Microsoft/vscode

#92031 is requesting a terminal CLI to enable things like creating a new tab and splitting the current tab which would align with the capabilities of many terminals (including Windows Terminal) and enable splitting a terminal tab by running a command in the terminal.

Does anyone have opinions for or against this? If we want to go with this I think we should also do the same for extensions by deprecating/aliasing the current CLI and moving them to either code ext ... or code extension ... as it keeps growing and could be better organized:

Extensions Management
  --extensions-dir <dir>                            Set the root path for
                                                    extensions.
  --list-extensions                                 List the installed
                                                    extensions.
  --show-versions                                   Show versions of installed
                                                    extensions, when using
                                                    --list-extension.
  --category                                        Filters installed
                                                    extensions by provided
                                                    category, when using
                                                    --list-extension.
  --install-extension <extension-id | path-to-vsix> Installs or updates the
                                                    extension. Use `--force`
                                                    argument to avoid
                                                    prompts.
  --uninstall-extension <extension-id>              Uninstalls an extension.
  --enable-proposed-api <extension-id>              Enables proposed API
                                                    features for extensions.
                                                    Can receive one or more
                                                    extension IDs to enable
                                                    individually.

[sbatten]

I really find CLIs that use this approach much easier to use. I would be in favor of having commands like code ext install over code --install-extension because they are easier to remember and type.

[bpasero]

I personally would prefer to not introduce any more capabilities via the CLI other than:

• opening something (this is what code is for)
• extension management: simply because this is probably a task that admins want to run headless and it does run headless
• troubleshooting (I think this is easy to justify)

[Tyriar]

I personally would prefer to not introduce any more capabilities via the CLI other than

@bpasero why though?

Most of the proposed terminal ones (new tab, split pane, focus at/next/prev) would simply just route commands to the last active renderer so they could be built relatively easily. Extending upon this, the use case could also be enabled by a generic command CLI:

code --command workbench.action.terminal.split
code --command workbench.action.terminal.focusAtIndex 3

[roblourens]

and enable splitting a terminal tab by running a command in the terminal

Why do people want to do that when it seems easier to go through the normal vscode command palette/UI?

[vscodebot]

This feature request is now a candidate for our backlog. The community has 60 days to upvote the issue. If it receives 20 upvotes we will move it to our backlog. If not, we will close it. To learn more about how we handle feature requests, please see our documentation.

Happy Coding!

[bpasero]

@bpasero why though?

Couple of reasons, I personally find that when someone types code --help we should really try to not overwhelm the user with all the possibilities and show an absolute minimum set to get things going.

On top of that, the CLI should drive the main capacity of the application, not some part within. You cannot even split the editor from the command line, so why the terminal?

[Tyriar]

@roblourens so you could for example have an alias to split the terminal (alias cs=code terminal split-pane) and so tools that do this for existing terminals can support vscode ranyitz/newsh#11

Couple of reasons, I personally find that when someone types code --help we should really try to not overwhelm the user with all the possibilities and show an absolute minimum set to get things going.

@bpasero That is exactly the problem this is trying to solve. We could change this:

Extensions Management
  --extensions-dir <dir>                            Set the root path for
                                                    extensions.
  --list-extensions                                 List the installed
                                                    extensions.
  --show-versions                                   Show versions of installed
                                                    extensions, when using
                                                    --list-extension.
  --category                                        Filters installed
                                                    extensions by provided
                                                    category, when using
                                                    --list-extension.
  --install-extension <extension-id | path-to-vsix> Installs or updates the
                                                    extension. Use `--force`
                                                    argument to avoid
                                                    prompts.
  --uninstall-extension <extension-id>              Uninstalls an extension.
  --enable-proposed-api <extension-id>              Enables proposed API
                                                    features for extensions.
                                                    Can receive one or more
                                                    extension IDs to enable
                                                    individually.

Into this (more potential to move window management, troubleshooting into their own too):

Commands:
  - extension              Extension management

On top of that, the CLI should drive the main capacity of the application, not some part within. You cannot even split the editor from the command line, so why the terminal?

If you're purely against driving the terminal and not namespaces in the CLI you should move your 👎 to #92031

[bpasero]

@Tyriar ah sorry, makes sense. I think this could work but we need to somehow preserve backwards compatibility, no? And I wonder if this is really worth the effort, I mean it would only impact extension management and diagnostics right? Alternatively we could ship a code-ext global command (via npx?) for managing extensions via CLI?

[Tyriar]

@bpasero yes backwards compat is essential, so --install-extension ... would be an alias for extension install .... If it were just extension management then it wouldn't be worth it, but right now I don't feel like we can enhance the CLI any further as it clutters code -h too much.

[bpasero]

Back to the original proposal of doing this because people want to control the terminal via CLI, is that really a scenario people want? Are they in an integrated terminal, type code split-terminal... to split the terminal instead of just using the keyboard that would do this in a fraction of the time it needs to start a Code.exe process?

[Tyriar]

@bpasero there's a terminal-agnostic tool that does this which is where the requests initially came from eg. newsh --split (ranyitz/newsh#11). Windows Terminal also had this request, they have a keybindings system to let you configure these as well.

• Docs https://github.com/microsoft/terminal/blob/master/doc/user-docs/UsingCommandlineArguments.md#using-the-wtexe-commandline
• PR Add support for commandline args to wt.exe terminal#4023
• Request (almost 100 👍) Feature Request: wt.exe supports command line arguments (profile, command, directory, etc.) terminal#607

But no, I probably wouldn't use these and don't feel that passionate about championing the feature. And if we don't do that, then namespacing probably isn't a good idea until we come up with another category.

[bpasero]

I suggest to close this as "out of scope".

[aeschli]

Before starting any work, please let's agree here first. The cli already has many owners (@aeschli, @bpasero, @joaomoreno)

[Tyriar]

@aeschli definitely 👍. This came up yesterday in standup that @connor4312 was thinking about this.

Something I feel is missing is some approval process for adding new CLIs as well to ensure things are consistent, as this is similar to API. I added --shell-integration <shelltype> to main recently and I'm still unsure about the name. Technically it returns the directory for the shell integration script, but all *- dir args are used to set the directory.

[bpasero]

I think that CLI option should not appear in the list of most used entries when running --help.

[Tyriar]

I was on the fence here, I'll remove it for now. This is one of the big benefits of actioning this issue though in that we can document these options that are important but don't warrant being in code --help, without the user needing to dig through our code.

[aeschli]

Yes, we need some review and approval process. Feel free to assign me as reviewer.

@Tyriar We have locate-extension hat returns the location of an extension. Maybe call it --locate-shell-integration-dir

We only want the major arguments to be listed with --help. But I agree we need something like --help --verbose or --help2 for the rest of the arguments.

[connor4312]

As the CLI does more things (server distro, "gateway" mode, version management, terminal work, other things in the future...) I do not think the current model of free-floating flags works very well. Note that when I say CLI here I refer to the interface exposed to users, which is eventually the Rust CLI.

Currently there is top-level help for extension management and flags that only apply to extension management. Adding similar sections for all other functionality causes help to become increasingly verbose and less useful to users, and I think a --help --verbose option does not address the root problem and is obscure to users. I suggest adopting a subcommand approach, where based editor options are shown at the top level (so code --wait foo.txt for instance still works) but the additional functionality I listed previously appears in a subcommand. If I'm a user who knows I want to do things with extensions, I can run code ext --help rather than trying to code --help --verbose | grep -B 5 -A 5 -i extension.

This is the approach I recently took in https://github.com/microsoft/vscode-cli/pull/432 (this is exploration, not final set in stone.) That PR includes logic that handles things that became subcommands (--(list|install|uninstall|)-extensions, --status) in a backwards compatible way.