Skip to content
Tutorials Center
My learning

Topics

C# Reference ยท .NET, Tools and Concepts

The dotnet CLI

Reference for the dotnet command-line tool: create, restore, build, run, test and publish projects, add packages, run single-file programs and pass arguments.

The dotnet command is the front door to everything in the .NET SDK. It creates projects from templates, downloads NuGet packages, compiles, runs tests, formats code and produces the files you deploy. The same commands work in a terminal on Windows, macOS and Linux, and every IDE (Visual Studio, Rider, VS Code) calls them under the hood.

A typical session from an empty folder looks like this:

Terminal
dotnet new console -o Hello
cd Hello
dotnet run

The runner on this site has no dotnet command and no shell for C#, so the command lines below are read-only. The runnable examples show how a program receives what you type after -- and how it can ask which runtime it runs on.

Try it

dotnet run -- one two passes one and two to your program. In top-level statements they arrive as the predefined array args. In the editor there are none, so this example supplies its own list to show the usual parsing pattern.

C# Reading command-line arguments

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.

C# Which runtime am I on?

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.

Syntax

The general form is dotnet [command] [arguments] [options]. Arguments for your own program go after a lone --.

Terminal
dotnet new console -n Tool            # create a project from a template
dotnet add package Humanizer          # add a NuGet package reference
dotnet restore                        # download packages
dotnet build -c Release               # compile
dotnet run -- --name Ada              # build if needed, then run
dotnet test                           # run unit tests
dotnet publish -c Release -o out      # produce files to deploy

Common commands

Command Description
dotnet new <template> Creates a project or file. dotnet new list shows templates such as console, classlib, web, webapi, worker, xunit, sln, gitignore, editorconfig.
dotnet restore Downloads the packages listed in the project. Run automatically by build and run.
dotnet build Compiles the project and its references. Default configuration is Debug; use -c Release for optimized output.
dotnet run Builds and starts the project. --project <path> chooses a project; -- <args> passes arguments to the program.
dotnet test Builds the test project and runs its tests through the test host.
dotnet publish Creates a folder with everything needed to run. Options include -r <runtime-id>, --self-contained, -p:PublishSingleFile=true, -p:PublishAot=true.
dotnet add package / remove package Edits PackageReference items.
dotnet add reference Adds a ProjectReference.
dotnet list package Lists packages; --outdated, --vulnerable and --include-transitive are the useful switches.
dotnet format Applies code style and analyzer fixes from your .editorconfig.
dotnet watch Re-runs or hot-reloads the app when files change.
dotnet tool install Installs a .NET tool (-g for global, or a local manifest with dotnet new tool-manifest).
dotnet --info, --list-sdks, --list-runtimes Show what is installed.

Single-file programs

Since .NET 10 you can run one .cs file without a project:

Terminal
dotnet run hello.cs

Special #: lines at the top of the file replace the project file, for example #:package [email protected] or #:property LangVersion=preview. This is exactly the shape of a program in this site's editors, except that we cannot download packages.

Exit codes: dotnet returns the exit code of the command. A build with errors returns non-zero, and a program that returns a number from Main (or from top-level statements) passes that number on.

Usage notes

  • build and run restore first. You rarely call dotnet restore by hand, except in a build pipeline that wants a separate, cacheable step.
  • Debug versus Release. Debug keeps extra information and skips optimization. Release turns optimizations on and removes Debug.Assert calls. Always measure and deploy Release.
  • The -- separator. Everything before it is for dotnet, everything after is for your program. Without it, dotnet run --help shows the help of dotnet run, not of your app.
  • Several SDKs can be installed side by side. A global.json file in a folder pins the SDK version used there, which keeps a team on the same compiler.
  • Framework-dependent versus self-contained. The default publish needs the runtime installed on the target machine and is small. --self-contained bundles the runtime, which is larger but needs nothing installed. Native AOT goes further and compiles to a native executable (Native AOT and trimming).
  • Runtime identifiers. -r win-x64, linux-x64, linux-arm64, osx-arm64 select the target operating system and processor for self-contained publishing.
  • Environment variables. DOTNET_ENVIRONMENT and ASPNETCORE_ENVIRONMENT choose Development or Production for hosts. DOTNET_CLI_TELEMETRY_OPTOUT=1 switches off usage telemetry.
  • Tools are programs too. dotnet-ef, dotnet-format and dotnet-outdated are installed as .NET tools and called as dotnet ef, dotnet outdated.