Updates to the CLI commands reference (#1129)

* reviewed cli commands topics * removed byline * minor fixes * fixed broken links * addressed feedback * clarified language * fixed typo
dotnet · Oct 14, 2016 · c6ee3f5 · c6ee3f5
1 parent a86c77c
commit c6ee3f5
Show file tree

Hide file tree

Showing 10 changed files with 341 additions and 296 deletions.
diff --git a/docs/core/tools/dotnet-build.md b/docs/core/tools/dotnet-build.md
@@ -1,32 +1,31 @@
 ---
-title: dotnet-build
-description: dotnet-build
-keywords: .NET, .NET Core
+title: dotnet-build command | .NET Core SDK
+description: The dotnet-build command builds a project and all of its dependencies. 
+keywords: dotnet-build, CLI, CLI command, .NET Core
 author: mairaw
 manager: wpickett
-ms.date: 06/20/2016
+ms.date: 10/13/2016
 ms.topic: article
 ms.prod: .net-core
 ms.technology: .net-core-technologies
 ms.devlang: dotnet
 ms.assetid: 70285a83-4103-4617-be8b-d0e1e9a4a91d
 ---
 
-dotnet-build
-===========
+#dotnet-build
 
-## NAME 
+## Name 
 dotnet-build -- Builds a project and all of its dependencies 
 
-## SYNOPSIS
+## Synopsis
 
-`dotnet build [--output]  
+`dotnet build [--help] [--output]  
     [--build-base-path] [--framework]  
     [--configuration]  [--runtime] [--version-suffix]
     [--build-profile]  [--no-incremental] [--no-dependencies]
-    [<project>]`  
+    [<project>]`
 
-## DESCRIPTION
+## Description
 
 The `dotnet build` command builds multiple source file from a source project and its dependencies into a binary. 
 By default, the resulting binary is in Intermediate Language (IL) and has a DLL extension. 
@@ -55,31 +54,35 @@ In order to build an executable application instead of a library, you need a [sp
 }
 ```
 
-## OPTIONS
+## Options
 
-`-o`, `--output` [DIR]
+`-h|--help`
 
-Directory in which to place the built binaries. 
+Prints out a short help for the command.  
 
-`-b`, `--build-base-path` [DIR]
+`-o|--output <OUTPUT_DIRECTORY>`
+
+Directory in which to place the built binaries. You also need to define `--framework` when you specify this option.
+
+`-b|--build-base-path <OUTPUT_DIRECTORY>`
 
 Directory in which to place temporary outputs.
 
-`-f`, `--framework` [FRAMEWORK]
+`-f|--framework <FRAMEWORK>`
 
-Compiles for a specific framework. The framework needs to be defined in the project.json file.
+Compiles for a specific framework. The framework needs to be defined in the [project.json](project-json.md#frameworks) file.
 
-`-c`, `--configuration` [Debug|Release]
+`-c|--configuration [Debug|Release]`
 
-Defines a configuration under which to build.  If omitted, it defaults to Debug.
+Defines a configuration under which to build.  If omitted, it defaults to `Debug`.
 
-`-r`, `--runtime` [RUNTIME_IDENTIFIER]
+`-r|--runtime [RUNTIME_IDENTIFIER]`
 
-Target runtime to build for. 
+Target runtime to build for. For a list of Runtime Identifiers (RIDs) you can use, see the [RID catalog](../rid-catalog.md). 
 
-`--version-suffix` [VERSION_SUFFIX]
+`--version-suffix [VERSION_SUFFIX]`
 
-Defines what `*` should be replaced with in the version field in the project.json file. The format follows NuGet's version guidelines. 
+Defines what `*` should be replaced with in the version field in the [project.json](project-json.md#version) file. The format follows NuGet's version guidelines. 
 
 `--build-profile`
 
@@ -92,3 +95,17 @@ Marks the build as unsafe for incremental build. This turns off incremental comp
 `--no-dependencies`
 
 Ignores project-to-project references and only builds the root project specified to build.
+
+## Examples
+
+Build a project and its dependencies:
+
+`dotnet build`
+
+Build a project and its dependencies using Release configuration:
+
+`dotnet build --configuration Release`
+
+Build a project and its dependencies for a specific runtime (in this example, Ubuntu 16.04):
+
+`dotnet build --runtime ubuntu.16.04-x64`
diff --git a/docs/core/tools/dotnet-install-script.md b/docs/core/tools/dotnet-install-script.md
@@ -1,37 +1,36 @@
 ---
-title: dotnet-install scripts reference
-description: dotnet-install scripts reference
-keywords: .NET, .NET Core
+title: dotnet-install scripts | .NET Core SDK
+description: Learn about the dotnet-install scripts to install the .NET Core CLI tools and the shared runtime. 
+keywords: dotnet-install, dotnet-install scripts, .NET Core
 author: mairaw
 manager: wpickett
-ms.date: 06/20/2016
+ms.date: 10/12/2016
 ms.topic: article
 ms.prod: .net-core
 ms.technology: .net-core-technologies
 ms.devlang: dotnet
 ms.assetid: 59b9c456-2bfd-4adc-8202-a1c6a0a6c787
 ---
 
-dotnet-install scripts reference
-================================
+#dotnet-install scripts reference
 
-## NAME
-dotnet-install.ps1 | dotnet-install.sh - script used to install the Command Line Interface (CLI) tools and shared runtime
+## Name
+dotnet-install.ps1 | dotnet-install.sh - script used to install the Command Line Interface (CLI) tools and the shared runtime
 
-## SYNOPSIS
+## Synopsis
 Windows:
 
 `dotnet-install.ps1 [-Channel] [-Version]
     [-InstallDir] [-Debug] [-NoPath] 
     [-SharedRuntime]`
 
-OS X/Linux:
+macOS/Linux:
 
 `dotnet-install.sh [--channel] [--version]
     [--install-dir] [--debug] [--no-path] 
     [--shared-runtime]`
 
-## DESCRIPTION
+## Description
 The `dotnet-install` scripts are used to perform a non-admin install of the CLI toolchain and the shared runtime. You can download the scripts from our [CLI GitHub repo](https://github.com/dotnet/cli/tree/rel/1.0.0-preview2/scripts/obtain). 
 
 Their main use case is to help with automation scenarios and non-admin installations. There are two scripts, one for PowerShell that works on Windows and a bash script that works on Linux/OS X. They both have the same behavior. Bash script also "understands" PowerShell switches so you can use them across the board. 
@@ -43,7 +42,7 @@ By default, the script will add the install location to the $PATH for the curren
 
 Before running the script, please install all the required [dependencies](https://github.com/dotnet/core/blob/master/Documentation/prereqs.md).
 
-You can install a specific version using the `--version` argument. The version needs to be specified as 3-part version (for example 1.0.0-13232). If omitted, it will default to the first global.json file found in the hierarchy above the folder where the script was invoked in that contains the `sdkVersion` property. If that is not present, it will use Latest.
+You can install a specific version using the `--version` argument. The version needs to be specified as 3-part version (for example, 1.0.0-13232). If omitted, it will default to the first [global.json](global-json.md) file found in the hierarchy above the folder where the script was invoked in that contains the `sdkVersion` property. If that is not present, it will use Latest.
 
 You can also use this script to get the SDK or shared runtime debug binaries with debug symbols by using the `--debug` argument. If you do not do this on first install and realize you do need debug symbols later on, you can re-run the script with this argument and the version of the bits you installed. 
 
@@ -53,83 +52,75 @@ Options are different between script implementations.
 ### PowerShell (Windows)
 `-Channel [CHANNEL]`
 
-Which channel (for example, "future", "preview", "production") to install from. The default value is "Production".
+Which channel (for example, `future`, `preview`, `production`) to install from. The default value is `production`.
 
 `-Version [VERSION]`
 
-Which version of CLI to install; you need to specify the version as 3-part version (i.e. 1.0.0-13232). If omitted, it will default to the first global.json that contains the sdkVersion property; if that is not present, it will use Latest. 	
+Which version of CLI to install; you need to specify the version as 3-part version (for example, 1.0.0-13232). If omitted, it will default to the first [global.json](global-json.md) that contains the [sdkVersion](global-json.md#sdkversion) property; if that is not present, it will use Latest. 	
 
 `-InstallDir [DIR]`
 
-Path to install to. The directory is created if it doesn't exist. The default value is `%LocalAppData%\.dotnet`.
+Path to install to. The directory is created if it doesn't exist. The default value is *%LocalAppData%\.dotnet*.
 
 `-Debug`
 
-**true** to indicate that larger packages containing debugging symbols should be used; otherwise, **false**. The default value is **false**.
+`true` to indicate that larger packages containing debugging symbols should be used; otherwise, `false`. The default value is `false`.
 
 `-NoPath`
 
-**true** to indicate that the prefix/installdir are not exported to the path for the current session; otherwise, **false**. 
-The default value is **false**, that is, the PATH is modified. 
+`true` to indicate that the prefix/installdir are not exported to the path for the current session; otherwise, `false`. 
+The default value is `false`, that is, the PATH is modified. 
 This makes the CLI tools available immediately after install. 
 
 `-SharedRuntime`
 
-**true** to install just the shared runtime bits; **false** to install the entire SDK. The default value is **false**.
+`true` to install just the shared runtime bits; `false` to install the entire SDK. The default value is `false`.
 
-### Bash (OS X/Linux)
+### Bash (macOS/Linux)
 `--channel [CHANNEL]`
 
 Which channel (for example "future", "preview", "production") to install from. The default value is "Production".
 
 `--version [VERSION]`
 
-Which version of CLI to install; you need to specify the version as 3-part version (i.e. 1.0.0-13232). If omitted, it will default to the first global.json that contains the sdkVersion property; if that is not present, it will use Latest. 	
+Which version of CLI to install; you need to specify the version as 3-part version (for example, 1.0.0-13232). If omitted, it will default to the first [global.json](global-json.md) that contains the [sdkVersion](global-json.md#sdkversion) property; if that is not present, it will use Latest. 	
 
 `--install-dir [DIR]`
 
 Path to where to install. The directory is created if it doesn't exist. The default value is `$HOME/.dotnet`.
 
 `--debug`
 
-**true** to indicate that larger packages containing debugging symbols should be used; otherwise, **false**. The default value is **false**.
+`true` to indicate that larger packages containing debugging symbols should be used; otherwise, `false`. The default value is `false`.
 
 `--no-path`
 
-**true** to indicate that the prefix/installdir are not exported to the path for the current session; otherwise, **false**. 
-The default value is **false**, that is, the PATH is modified. 
+`true` to indicate that the prefix/installdir are not exported to the path for the current session; otherwise, `false`. 
+The default value is `false`, that is, the PATH is modified. 
 This makes the CLI tools available immediately after install.  
 
 `--shared-runtime`
 
-**true** to install just the shared runtime bits; **false** to install the entire SDK. The default value is **false**.
+`true` to install just the shared runtime bits; `false` to install the entire SDK. The default value is `false`.
 
-## EXAMPLES
+## Examples
+
+Install the dev latest version to the default location:
 
 Windows:
 
-```
-./dotnet-install.ps1 -Channel Future
-```
+`./dotnet-install.ps1 -Channel Future`
 
-OS X/Linux:
+macOS/Linux:
 
-```
-./dotnet-install.sh --channel Future
-```
+`./dotnet-install.sh --channel Future`
 
-Installs the dev latest version to the default location.
+Install the latest preview to the specified location:
 
 Windows:
 
-```
-./dotnet-install.ps1 -Channel preview -InstallDir C:\cli
-```
-
-OS X/Linux:
+`./dotnet-install.ps1 -Channel preview -InstallDir C:\cli`
 
-```
-./dotnet-install.sh --channel preview --install-dir ~/cli
-```
+macOS/Linux:
 
-Installs the latest preview to the specified location.
+`./dotnet-install.sh --channel preview --install-dir ~/cli`
diff --git a/docs/core/tools/dotnet-new.md b/docs/core/tools/dotnet-new.md
@@ -1,30 +1,29 @@
 ---
-title: dotnet-new
-description: dotnet-new
-keywords: .NET, .NET Core
+title: dotnet-new command | .NET Core
+description: The dotnet-new command creates new .NET Core projects in the current directory.
+keywords: dotnet-new, CLI, CLI command, .NET Core
 author: mairaw
 manager: wpickett
-ms.date: 06/20/2016
+ms.date: 10/12/2016
 ms.topic: article
 ms.prod: .net-core
 ms.technology: .net-core-technologies
 ms.devlang: dotnet
 ms.assetid: 263c3d05-3a47-46a6-8023-3ca16b488410
 ---
 
-dotnet-new
-==========
+#dotnet-new
 
-## NAME
-dotnet-new -- Creates a new .NET Core project
+## Name
+dotnet-new -- Creates a new .NET Core project in the current directory
 
-## SYNOPSIS
-`dotnet new [--type] [--lang]`
+## Synopsis
+`dotnet new [--help] [--type] [--lang]`
 
-## DESCRIPTION
+## Description
 The `dotnet new` command provides a convenient way to initialize a valid .NET Core project and sample source code to try out the Command Line Interface (CLI) toolset. 
 
-This command is invoked in the context of a directory. When invoked, the command will result in two main artifacts being dropped to the directory: 
+This command is invoked in the context of a directory. When invoked, the command will result in two main artifacts being dropped to the current directory: 
 
 1. A `Program.cs` (or `Program.fs`) file that contains a sample "Hello World" program.
 2. A valid `project.json` file.
@@ -33,28 +32,28 @@ After this, the project is ready to be compiled and/or edited further.
 
 ## Options
 
-`-l`, `--lang [C#|F#]`
+`-h|--help`
 
-Language of the project. Defaults to `C#`. `csharp` (`fsharp`) or `cs` (`fs`) are also valid options.
+Prints out a short help for the command.  
 
-`-t`, `--type`
+`-l|--lang <C#|F#>`
 
-Type of the project. Valid values are `console`, `web`, `lib` and `xunittest`. 
+Language of the project. Defaults to `C#`. Other valid values are `csharp`, `fsharp`, `cs` and `fs`.
 
-## EXAMPLES
+`-t|--type`
 
-`dotnet new`
-
-Drops a C# project in the current directory.
+Type of the project. Valid values for C# are `console`, `web`, `lib` and `xunittest` and for F# only `console` is valid. 
 
-`dotnet new --lang f#`
-    
-Drops an F# project in the current directory.
+## Examples
+
+Create a C# console application project in the current directory:
 
-`dotnet new --lang c#`
-
-Drops an C# project in the current directory.
+`dotnet new` or `dotnet new --lang c#` 
+
+Create an F# console application project in the current directory:
+
+`dotnet new --lang f#`
+
+Create a new ASP.NET Core C# application project in the current directory:
 
-`dotnet new -t web`
-
-Drops a new ASP.NET Core project in the current directory. 
+`dotnet new -t web`