.NET Core CLI Documentation

The .NET Command-Line Interface (CLI) is a cross-platform toolchain that enables you to build, test, and deploy .NET applications.

This documentation provides a comprehensive guide to the commands, options, and common use cases of the .NET CLI. Whether you're creating a new project, managing dependencies, or publishing your application, the .NET CLI is your primary tool.

Introduction to the .NET CLI

The .NET CLI is installed as part of the .NET SDK. You can invoke CLI commands from any directory in your terminal or command prompt.

The basic syntax for most commands is:

dotnet <command> [<arguments>] [<options>]

For example, to create a new console application:

dotnet new console -n MyConsoleApp

Core Commands

dotnet new

Creates a new .NET project or solution from a template.

dotnet new <TEMPLATE> [-n|--name <OUTPUT_NAME>] [-o|--output <OUTPUT_DIRECTORY>] [-lang|--language <LANGUAGE>] [--force] [--list] [--help]

Common templates include:

• console: A simple command-line application.
• classlib: A class library.
• web: An ASP.NET Core web application.
• mstest: A unit test project with MSTest.
• nunit: A unit test project with NUnit.
• xunit: A unit test project with xUnit.

Example:

dotnet new webapp -n MyWebApp -o ./src/WebApp --language F#

dotnet build

Compiles a .NET project.

dotnet build [<PROJECT>] [--configuration <CONFIGURATION>] [--output <OUTPUT_DIRECTORY>] [--no-restore] [--no-dependencies] [--framework <FRAMEWORK>] [--runtime <RUNTIME_IDENTIFIER>] [--version-suffix <VERSION_SUFFIX>] [--help]

Example:

dotnet build --configuration Release --output ./bin/Release

dotnet run

Compiles and runs a .NET project. Useful for local development and testing.

dotnet run [<PROJECT>] [--configuration <CONFIGURATION>] [--runtime <RUNTIME_IDENTIFIER>] [--no-build] [--no-dependencies] [--no-restore] [--launch-profile <NAME>] [--filter <EXPRESSION>] [--help]

Example:

dotnet run --project ./src/MyProject --configuration Debug

dotnet publish

Publishes a .NET application for deployment. Creates self-contained applications or framework-dependent applications.

dotnet publish [<PROJECT>] [--configuration <CONFIGURATION>] [--output <OUTPUT_DIRECTORY>] [--runtime <RUNTIME_IDENTIFIER>] [--no-build] [--no-restore] [--no-dependencies] [--self-contained true|false] [--arch <ARCHITECTURE>] [--framework <FRAMEWORK>] [--version-suffix <VERSION_SUFFIX>] [--force] [--help]

Example (self-contained for Linux):

dotnet publish --configuration Release --runtime linux-x64 --self-contained true --output ./publish/linux

dotnet test

Runs unit tests using the specified test runner.

dotnet test [<PROJECT>] [--configuration <CONFIGURATION>] [--filter <EXPRESSION>] [--logger <LOGGER>] [--no-build] [--no-restore] [--data-collection-diagnostic-messages <FILE>] [--data-collection-settings <FILE>] [--diag <FILE>] [--environment <NAME=VALUE>] [--port <PORT>] [--collect <URI>] [--settings <FILE>] [--help]

Example:

dotnet test --configuration Release --filter "Category=Integration"

dotnet add

Adds reference to a project or package.

dotnet add [<PROJECT>] package <PACKAGE_NAME> [--version <VERSION>] [--prerelease] [--tool-path <PATH>] [--help]
dotnet add [<PROJECT>] reference <PROJECT_REFERENCE> [--help]

Example (add a package):

dotnet add MyProject.csproj package Newtonsoft.Json --version 13.0.1

Example (add a project reference):

dotnet add src/MyWebApp/MyWebApp.csproj reference ../MyLibrary/MyLibrary.csproj

dotnet remove

Removes a reference from a project.

dotnet remove [<PROJECT>] package <PACKAGE_NAME> [--help]
dotnet remove [<PROJECT>] reference <PROJECT_REFERENCE> [--help]

Example:

dotnet remove MyProject.csproj package Newtonsoft.Json

dotnet restore

Restores the .NET project's dependencies.

dotnet restore [<PROJECT>] [--configfile <FILE>] [--disable-restore-package-imports] [--ignore-failed-sources] [--include-assets <TYPE>] [--include-source <SOURCE>] [--interactive] [--lock-file-path <PATH>] [--no-dependencies] [--no-incremental] [--no-parallel] [--no-propagate-inference-layers] [--packages <PATH>] [--recursive] [--runtime <RUNTIME_IDENTIFIER>] [--source <SOURCE>] [--use-lock-file] [--validate-only] [--verbosity <VERBOSITY>] [--help]

Example:

dotnet restore --configfile ./NuGet.Config

dotnet clean

Cleans the output of a .NET project.

dotnet clean [<PROJECT>] [--configuration <CONFIGURATION>] [--output <OUTPUT_DIRECTORY>] [--no-restore] [--help]

Example:

dotnet clean --configuration Release

dotnet sdk

Manages .NET SDK installations.

dotnet sdk commands [--list] [--install] [--uninstall] [--help]

Example:

dotnet sdk list

dotnet tool

Manages .NET tools (global and local).

dotnet tool install <TOOL_NAME> [--version <VERSION>] [--global] [--local] [--tool-path <PATH>] [--help]
dotnet tool uninstall [--global|--local] <TOOL_NAME> [--tool-path <PATH>] [--help]
dotnet tool list [--global|--local] [--tool-path <PATH>] [--help]
dotnet tool update [--global|--local] <TOOL_NAME> [--tool-path <PATH>] [--help]

Example (install a global tool):

dotnet tool install --global dotnet-ef --version 6.0.1

dotnet migrate

Migrates a project.json project to the MSBuild format (.csproj).

dotnet migrate [<PROJECT>] [--framework <FRAMEWORK>] [--ignore-failed-sources] [--skip-backup] [--help]

This command is less commonly used now with modern project creation.

dotnet list

Lists project references and package dependencies.

dotnet list [<PROJECT>] reference [--framework <FRAMEWORK>] [--help]
dotnet list [<PROJECT>] package [--framework <FRAMEWORK>] [--include-transitive] [--help]

Example:

dotnet list MyProject.csproj package --framework net6.0

dotnet search

Searches for NuGet packages.

dotnet search <QUERY> [--prerelease] [--size <SIZE>] [--skip <SKIP>] [--source <SOURCE>] [--help]

Example:

dotnet search aspnet --prerelease

dotnet store

Stores a .NET SDK or NuGet package in the local store.

dotnet store --framework <FRAMEWORK> [--runtime <RUNTIME_IDENTIFIER>] [--help]

dotnet nugets

Manages NuGet package sources.

dotnet nugets add source <SOURCE> [--name <NAME>] [--priority <PRIORITY>] [--store-password-in-clear-text] [--configfile <FILE>] [--help]
dotnet nugets remove source <NAME> [--configfile <FILE>] [--help]
dotnet nugets list [--configfile <FILE>] [--help]

Example:

dotnet nugets add source https://api.nuget.org/v3/index.json --name NuGetOrg

dotnet workload

Manages .NET SDK workloads (e.g., MAUI, Xamarin).

dotnet workload install <WORKLOAD_ID> [--from-nowhere] [--include-previews] [--skip-manifest-update] [--help]
dotnet workload uninstall <WORKLOAD_ID> [--help]
dotnet workload list [--include-installed] [--include-all] [--help]
dotnet workload repair [--help]

Example:

dotnet workload install maui

Common Workflows

Here are a few common development workflows using the .NET CLI:

Creating a New Project

To create a new ASP.NET Core Razor Pages project named "MyWebApp" in the current directory:

dotnet new webapp -n MyWebApp

To create a class library named "MyLibrary" in a specific output directory:

dotnet new classlib -n MyLibrary -o ./src/MyLibrary

Developing and Testing

Navigate into your project directory and use dotnet run for development and dotnet test to run your unit tests.

cd MyConsoleApp
dotnet run

cd MyProject
dotnet test

Publishing for Deployment

To publish a self-contained application for Windows (x64) in Release mode:

dotnet publish --configuration Release --runtime win-x64 --self-contained true --output ./publish/win64

To publish a framework-dependent application for Linux:

dotnet publish --configuration Release --runtime linux-x64 --output ./publish/linux