What is and how to use the .NET CLI

6 min
Advanced

The CLI of .NET is a command-line interface provided by the .NET SDK that allows you to perform tasks and actions to manage .NET projects.

With the CLI, we can create, compile, run, and manage .NET projects without the need for a graphical environment (like Visual Studio).

This is often faster and more efficient than doing it from an IDE. Additionally, it allows us to automate tasks and workflows.

Here is the table with simple and discreet emojis:

Feature	CLI	Visual Studio
Speed	🟢 Fast	🔴 Slower
Control	🟢 Granular	🔴 Limited
Automation	🟢 Excellent	🔴 Limited
Interface	Terminal	GUI
Requirements	🟢 Just SDK	🔴 Full IDE

The .NET SDK CLI is like your Swiss army knife for C# developers. It provides you with a comprehensive set of utilities to perform any development task for applications in the .NET environment.

Besides, using the console makes you feel like a hacker, which is not bad at all.

As it is a tool you will use frequently, let’s see how to use it 👇

Verify the installation of .NET SDK

Before starting, we should logically verify that the .NET SDK is correctly installed. To do this, run the following command:

dotnet --version

This command will show the installed version of the SDK. If you do not see a version, make sure that the SDK is correctly installed and that the CLI path is in your PATH environment variable.

If you do not have the .NET SDK installed, we covered it in

How to install .NET

Basic command structure

The .NET CLI is a command-line interface. This means it runs and responds through a terminal (like CMD or PS).

All commands look more or less the same and follow the pattern:

dotnet [command] [arguments] [options]

Some of the most common commands are:

Command	Description	Example
`new`	Creates new projects	`dotnet new console`
`restore`	Restores dependencies	`dotnet restore`
`build`	Compiles the project	`dotnet build`
`run`	Runs the project	`dotnet run`
`test`	Runs tests	`dotnet test`
`add`	Adds packages/references	`dotnet add package Newtonsoft.Json`
`publish`	Publishes for deployment	`dotnet publish -c Release`

Creating projects

One of the most common functions of the CLI is to create a new project using the dotnet new command. This command supports predefined templates for different types of projects.

For example, if we want to create a new web API project, we would do it like this:

dotnet new webapi -n MyFirstApi

webapi: This is the type of project we want to create (console, webapi…)
-n: Project name
-o: Output directory
-f: .NET version

This command will create a folder called MyFirstApi with the basic structure of a web API project.

Available template types

If you want to see the templates you have installed on your machine, you can do:

dotnet new list  # Lists all templates

Some of the most common templates are:

console: Console application
webapi: REST API
mvc: MVC web application
classlib: Class library
xunit: Test project

Dependency management

With the CLI, we can also manage the dependencies of our project.

Add NuGet packages

NuGet packages are external libraries that you can add to your project to extend its functionality. To add a package, we use the dotnet add package command.

For example, to add the Microsoft.EntityFrameworkCore package:

dotnet add package Microsoft.EntityFrameworkCore

This command will download and install the package in your project, and automatically add it to the .csproj file.

Reference other projects

We can also add a reference to another project:

dotnet add reference ../MyClassLib/MyClassLib.csproj

Restore dependencies

When you clone an existing project or add new packages, you may need to restore the dependencies. For that, use the dotnet restore command.

dotnet restore

This command will download all the necessary dependencies to compile and run the project.

Build and run

Of course, we can also run and compile our project.

Run

Run a project

To run an ASP.NET Core project, use the dotnet run command. This command compiles the project (if necessary) and runs it.

dotnet run

Build

Build a project

Once you have created a project, you can build it using the dotnet build command. This command compiles the source code and generates the binary files needed to run the application.

dotnet build

If the project compiles successfully, you will see a success message in the terminal. If there are errors, the CLI will show you details about the problems encountered.

Useful options:

-c|—configuration: Debug/Release (-c release)
-r|—runtime: Specify Runtime Identifier RID (-r linux-x64)
—no-restore: Skip restore

If you need to pass parameters to the executable, you can do it like this:

dotnet run -- arg1 arg2

For example:

dotnet run --urls=http://localhost:8080

Clean

Clean the project

If you want to delete the files generated during the build, you can use the dotnet clean command.

dotnet clean

This command will remove the bin and obj folders, which contain the binary and temporary files generated during the build.

Run tests

If your project includes unit tests, you can run them using the dotnet test command.

dotnet test

This command will look for all the test projects in the solution and run the tests.

Publishing an application

When you are ready to deploy your application, you can use the dotnet publish command to generate the files necessary for publication.

dotnet publish -c Release -o ./publish

This command compiles the project in Release mode and places the resulting files in the ./publish folder.

To distribute a compiled application:

dotnet publish -c Release -r win-x64 --self-contained true

This generates a self-contained executable for Windows. You can change win-x64 to linux-x64 or osx-x64 depending on the target system.

Global Tools

The CLI also allows us to install global tools. These are NuGet packages that contain console applications that can be installed and run from anywhere on your machine.

These tools are useful for development tasks, automation, or any utility you need to have available globally.

Command	Description
`dotnet tool install -g <ToolName>`	Installs a tool globally
`dotnet tool update -g <ToolName>`	Updates a global tool
`dotnet tool list -g`	Lists all installed global tools
`dotnet tool uninstall -g <ToolName>`	Uninstalls a global tool

For example, if we want to install the dotnet-ef tool to manage Entity Framework projects, we would do it like this:

# Install the 'dotnet-ef' tool globally
dotnet tool install -g dotnet-ef

# Run the tool 
dotnet ef