Thoughts regarding the dotnet cli UX

Thoughts regarding the dotnet cli UX

Yesterday I decided to have a look at the UX for the dotnet cli, and came to the conclusion that there are some things that I think might be possible to simplify, to make it easier for new people to adopt. The CLI is probably the first thing that people see when starting out with .NET Core, unless you are using VS, and because if this, I think it needs to be simple and easy to understand.

So here are some thoughts after looking through the UX.

dotnet

Just typing dotnet without any arguments currently returns a fairly large amount of text that probably isn’t very useful for a lot of people. So my suggestion is to simplify this view by making it shorter, and easier to read

C:\Users\Chris>dotnet

Usage: dotnet [options | path-to-application]

options:
  -v|--version          Display .NET CLI Version Number
  -i|--install          Install runtime
  -d|--diagnostics      Enable diagnostic output
  -ri|--runtime-info    Display Runtime Information

path-to-application:
  The path to a .NET Core managed application, dll or exe file to execute.

Version:
  Runtime:   1.1.0
  SDK:       1.0.1

To install SDK, run dotnet install --sdk

As you can see, the text is much shorter than the current one, making it easier to digest. To shorten it down, the options segment has removed, and is instead available through –help.

The information about the host configuration environment has been removed, and I suggest having that in the documentation instead. It seems like something a very small amount of people will use, so having it here is not useful for most people.

Version information has been moved to the bottom, as in most cases it is less important than the rest of the information. It also includes both runtime and SDK versions, as both versions are of interest in a lot of cases. Having one version here, and another when typing –version is confusing to me. The build hash has also been removed to make the information less verbose. The hash is not useful to more than a small group of people, so I suggest just moving it to the release notes instead.

I also suggest removing the text about installing the SDK, as it is not possible to click the link for obvious reasons, and copy pasting it is just cumbersome. Instead of having the text and copy pasting the URL, I suggest adding a new command called install with an argument like –sdk. Running just install installs the latest runtime instead of the SDK, making it easy to install new runtimes on servers etc, and by adding –sdk it changes and installs the latest SDK instead. Optionally it installs the specified version, if a specific version is provided.

If the install command is too complicated, at least changing the URL to a better URL would be good.

dotnet --runtime-info

I also suggest adding a new option called –runtime-info, which gives the user access to runtime information previously available through --info (which is removed). It is just a bit more clear to me what runtime-info means, opposed to info.

C:\Users\Chris>dotnet --runtime-info
OS Name:     Windows
OS Version:  10.0.14393
OS Platform: Windows
RID:         win10-x64

dotnet --help

Today, typing dotnet --help returns a lot of useful information, but I think the content could be simplified a bit. Something like this

C:\Users\Chris>dotnet -h

Usage: dotnet [command] [command-arguments] [options]

Runtime Commands:
  -v|--version          Display .NET CLI and SDK Version Number
  -i|--install          Install runtime
  -d|--diagnostics      Enable diagnostic output
  -ri|--runtime-info    Display Runtime Information

SDK Commands:
  new           Initialize .NET projects.
  restore       Restore dependencies specified in the .NET project.
  run           Compiles and immediately executes a .NET project.
  build         Builds a .NET project.
  publish       Publishes a .NET project for deployment (including the runtime).
  test          Runs unit tests using the test runner specified in the project.
  pack          Creates a NuGet package.
  migrate       Migrates a project.json based project to a msbuild based project.
  clean         Clean build output(s).
  sln           Modify solution (SLN) files.
  add           Add reference to the project
  remove        Remove reference from the project
  list          List reference in the project
  nuget         Provides additional NuGet commands.
  msbuild       Runs Microsoft Build Engine (MSBuild).
  vstest        Runs Microsoft Test Execution Command Line Tool.

Options:
  -v|--verbose                     Enable verbose output
  -h|--help                        Show help
  --fx-version <version>           Version of the installed runtime version to use to run the application.
  --additionalprobingpath <path>   Path containing probing policy and assemblies to probe for.

To make the help section easier to digest, I think removing the CLI version information, which is available through --version, makes sense. Once again, having 2 diferent versions popping up in different scenarios is confusing…

I think removing the arguments information would be good as well. Currently it only duplicated the “usage row”, and having it twice can be a little confusing and does not really give anything more to the user.

Renaming the “Host options” “Runtime Commands” would probably make them a bit easier to understand. And to make it consistent, this section replicates the information shown when running dotnet.

I would also suggest grouping all SDK commands into one section, as there is no real need to keep them separate. It only takes up space, and even though there might be technical differences between them, the average user probably doesn’t care.

Common Options can also be renamed to just Options, and moved to the end. Moving them to the end of the text, is in line with where they are used…

dotnet version

I would also suggest changing the experience around getting the versioning information.

Instead of having –version, I suggest introducing a new command called version. Having this as a command makes it more flexible as arguments can be added if needed. Running it without arguments displays the below information, containing both all available runtime versions, as well as latest SDK version and root path.

C:\Users\Chris>dotnet version

Runtime Versions:
  1.1.0
  1.0.1
  1.0.0

SDK Version:
  1.1.0 
  
Root path:   
  C:\Program Files\dotnet\

Having dotnet version return all installed runtime versions as well as the latest SDK would make a lot of sense to me. It explains the difference version numbers better, than showing different numbers depending on what you are doing. I also suggest having the Root Path in here (currently called base path)

However, I would suggest keeping dotnet --version for backwards compatibility, but having it undocumented in an attempt to get people to use the new command instead.

Adding a –sdk-version argument allows tooling to get an easily parsable string instead of having to parse the above verbose information.

C:\Users\Chris>dotnet version --sdk-version
1.1.0 

Any thoughts? Feedback? Comments?

[livarcocc]

I like the idea, as long as we don’t remove the existing commands (–info and --version). I am fine taking them out of the help options, but we should keep them in case people (and particularly CI) depend on them.

Though I don’t see much value in --runtime-info versus --info. I would rather just keep --info.

I agree with the other changes though.

cc @gkhanna79 for the proposed host changes.

[kamranayub]

As a brand new user to the CLI, running dotnet --version and not seeing what I expected was frustrating. However, I did run dotnet first to see how to find the version (even though -v, --version is pretty standard across the CLI ecosystem), and if there was dotnet version available, that would have solved my issue and been clearer with the multitude of versions to keep track of. Definitely +1 to dotnet version and deprecating/hiding --version to replace with specific “filter” parameters as @richlander suggested for CI systems or automation.