What is the .NET CLI, and what do dotnet new, dotnet build, dotnet run and dotnet clean do?

1. One executable, two jobs

 dotnet <something>
     |
     v
 muxer (dotnet / dotnet.exe, first on PATH)
     |
     +-- "something" is a .dll path  --> HOST mode
     |      dotnet Orders.Cli.dll
     |      reads Orders.Cli.runtimeconfig.json, finds the runtime,
     |      loads the app. No SDK needed.
     |
     +-- "something" is a command    --> SDK mode
            dotnet build / new / run / test / publish / tool ...
            hostfxr picks an SDK (global.json, else newest installed)
            and runs the command from dotnet/sdk/<version>/

A production server running a framework-dependent app only needs the runtime. A developer machine or CI agent needs the SDK, which includes a runtime plus the CLI, MSBuild, the compiler and templates.

2. How SDK commands map to MSBuild

Most commands are thin wrappers around MSBuild targets in the project:

That is why dotnet build -p:Configuration=Release and dotnet build -c Release are the same thing, and why anything you can do in a .csproj you can also pass on the command line with -p:.

3. What dotnet build does, step by step

 dotnet build -c Release
   |
   +-- 1. resolve the SDK               <-- global.json / newest installed
   |
   +-- 2. implicit restore
   |      read PackageReference items, resolve the dependency graph,
   |      download to ~/.nuget/packages, write obj/project.assets.json
   |
   +-- 3. evaluate the project
   |      .csproj + Directory.Build.props/.targets + SDK props/targets
   |      --> properties and items
   |
   +-- 4. run the target graph
   |      ResolveReferences --> CoreCompile (csc) --> copy outputs
   |      (skips targets whose inputs haven't changed: incremental)
   |
   v
 bin/Release/net10.0/
   Orders.Cli.dll                    your code (IL)
   Orders.Cli.pdb                    symbols
   Orders.Cli.deps.json              dependency list for the host
   Orders.Cli.runtimeconfig.json     which runtime version to use
   Orders.Cli(.exe)                  apphost launcher
   Orders.Domain.dll                 referenced project
 obj/Release/net10.0/                intermediate files, file lists

The second build is much faster because MSBuild compares input and output timestamps and skips work that is up to date, and the compiler server is already running.

4. dotnet new in more depth

Without -f, a template targets the newest framework the installed SDK supports, so pass it explicitly in scripts.

5. dotnet run in more depth

 dotnet run --project src/Orders.Cli -c Release -- --region australiaeast
            |                         |          |  |
            which project             config     |  arguments for YOUR app
                                                 separator

dotnet run is a development command. It checks for changes and may rebuild on every start, so production runs the published output instead.

6. dotnet clean and what it leaves behind

During a build, MSBuild writes a list of every file it produced to obj/<Configuration>/<TFM>/<Project>.csproj.FileListAbsolute.txt. dotnet clean deletes the files in that list.

For a stubborn problem, deleting bin/ and obj/ (and running dotnet build-server shutdown) is the bigger hammer. For package problems, dotnet nuget locals all --clear clears NuGet caches.

7. Useful options on most commands

8. .NET 10 CLI changes worth knowing

9. Performance

• MSBuild node reuse and the Roslyn compiler server keep processes warm between builds. dotnet build-server shutdown stops them if they hold stale state.
• In CI, restore once and pass --no-restore to later commands, and --no-build to test and publish after a build.
• -bl is the fastest way to see why a build is slow or why a target ran.

10. .NET 11 awareness

Treat CLI changes in .NET 11 previews as awareness only. Check the SDK release notes before relying on a new command or default in scripts.

11. Try it yourself

1. Run the commands in the code example.
2. Run dotnet build twice and compare the times.
3. Look in bin/Release/net10.0/ and open the .runtimeconfig.json and .deps.json files.
4. Run dotnet clean (no -c) and notice the Release output is still there; then run dotnet clean -c Release.
5. Run dotnet run --project src/Orders.Cli -- --region australiaeast, then try it without -- and read the error.
6. Build with -bl and open msbuild.binlog in the MSBuild Structured Log Viewer.
7. Create hello.cs containing Console.WriteLine("G'day"); and run dotnet run hello.cs.

Create a solution with a console app and a library, then build, run and clean:

dotnet new sln -n Orders
dotnet new console -n Orders.Cli -o src/Orders.Cli -f net10.0
dotnet new classlib -n Orders.Domain -o src/Orders.Domain -f net10.0
dotnet sln add src/Orders.Cli src/Orders.Domain
dotnet add src/Orders.Cli reference src/Orders.Domain

dotnet build -c Release
dotnet run --project src/Orders.Cli -- --region australiaeast
dotnet clean -c Release

src/Orders.Cli/Program.cs:

var region = args.SkipWhile(a => a != "--region").Skip(1).FirstOrDefault() ?? "australiaeast";
Console.WriteLine($"Orders CLI running for region {region} on {System.Runtime.InteropServices.RuntimeInformation.FrameworkDescription}");