Vscode-vsce: `vsce --help command` doesn't work

[vfonic]

I wanted to check if I can modify the package name when running vsce package so I typed:

$ vsce --help
Usage: vsce [options] [command]

Options:
  -V, --version                        output the version number
  -h, --help                           output usage information

Commands:
  ls [options]                         Lists all the files that will be published
  package [options]                    Packages an extension
  publish [options] [<version>]        Publishes an extension
  unpublish [options] [<extensionid>]  Unpublishes an extension. Example extension id: microsoft.csharp.
  ls-publishers                        List all known publishers
  create-publisher <publisher>         Creates a new publisher
  delete-publisher <publisher>         Deletes a publisher
  login <publisher>                    Add a publisher to the known publishers list
  logout <publisher>                   Remove a publisher from the known publishers list
  show [options] <extensionid>         Show extension metadata
  search [options] <text>              search extension gallery
  *

Then I typed:

$ vsce --help package
Usage: vsce [options] [command]

Options:
  -V, --version                        output the version number
  -h, --help                           output usage information

Commands:
  ls [options]                         Lists all the files that will be published
  package [options]                    Packages an extension
  publish [options] [<version>]        Publishes an extension
  unpublish [options] [<extensionid>]  Unpublishes an extension. Example extension id: microsoft.csharp.
  ls-publishers                        List all known publishers
  create-publisher <publisher>         Creates a new publisher
  delete-publisher <publisher>         Deletes a publisher
  login <publisher>                    Add a publisher to the known publishers list
  logout <publisher>                   Remove a publisher from the known publishers list
  show [options] <extensionid>         Show extension metadata
  search [options] <text>              search extension gallery
  *

...and any possible combination of help and package I could think of. None showed me what options vsce package takes. Any ideas how I can get that from shell, without having to dig through the code itself? Is it possible?

Thank you!

PS What's * command? 🤔

[joaomoreno]

There's only another combination 😄

$ vsce package --help
Usage: package [options]

Packages an extension

Options:
  -o, --out [path]        Output .vsix extension file to [path] location
  --baseContentUrl [url]  Prepend all relative links in README.md with this url.
  --baseImagesUrl [url]   Prepend all relative image links in README.md with this url.
  --yarn                  Use yarn instead of npm
  -h, --help              output usage information

[vfonic]

😁

Thanks for pointing that out!

However, I don't think that fixes the issue. The real issue here is developer experience (DX), which, in my opinion, is broken.

The help output clearly shows Usage: vsce [options] [command]
Yet, the real usage is: Usage: vsce [options] [command], maybe, if the option is not --help.

I'm not sure what's the Powershell defacto standard, but, as far I've seen, on Unix, most of the tools accept <cli-tool-name> help <command>. This being cross platform tool, would be great if on Unix it would work similarly how other tools work. Also, [command] (in square brackets) usually denotes optional argument.

Im not an expert CLI developer, but this is something I'd look into to get it right if I were building a CLI tool and I wanted to provide great user/developer experience.

[joaomoreno]

Good point. Let's make sure --help can go before the command.

[jamesgeorge007]

@joaomoreno @vfonic vsce <command> [options] is the intended way. While what shows up with --help is essentially misleading.

It could be resolved with a minor tweak here:-
https://github.com/microsoft/vscode-vsce/blob/e06834b9a10b246bc7747d170bfd08227fd46396/src/main.ts#L56

Just include usage('<command> [options]')

[jamesgeorge007]

@joaomoreno Shall I go ahead and shoot up a PR :thinking:

[joaomoreno]

Sure.