What are .NET tools, and how do global tools differ from local tools with a tool manifest and dotnet tool restore?

1. What a tool package is

A .NET tool is an ordinary console app packed with <PackAsTool>true</PackAsTool>. The package has a different type from a library package:

 Contoso.ReleaseNotes.1.2.0.nupkg      (package type: DotnetTool)
 +-- Contoso.ReleaseNotes.nuspec
 +-- tools/
     +-- net10.0/
         +-- any/
             +-- DotnetToolSettings.xml   command name -> entry point DLL
             +-- Contoso.ReleaseNotes.dll
             +-- (all its dependencies, bundled)

That is why dotnet add package dotnet-ef doesn't give you the dotnet ef command, and why a tool's dependencies never conflict with your project's.

2. How dotnet <command> is resolved

 dotnet ef migrations add Init
          |
          v
 built-in SDK command (build, test, new ...)?  --yes--> run it
          | no
          v
 walk up from the current directory looking for .config/dotnet-tools.json
 (and dotnet-tools.json in the folder itself); stop at a manifest with isRoot: true
          |
          +-- a manifest lists a tool with command "dotnet-ef"
          |      restored in ~/.nuget/packages?
          |        no  --> error: "Run 'dotnet tool restore'"
          |        yes --> run the PINNED version
          |
          | no manifest entry
          v
 an executable called dotnet-ef on PATH (a global tool)?  --yes--> run it
          | no
          v
 "Could not execute because the specified command or file was not found"

Two consequences: a local tool wins over a global tool with the same command, and the same command can run different versions in different folders.

3. The three install modes compared

4. The manifest in detail

{
  "version": 1,
  "isRoot": true,
  "tools": {
    "dotnet-ef": {
      "version": "10.0.0",
      "commands": ["dotnet-ef"],
      "rollForward": false
    },
    "csharpier": {
      "version": "1.0.2",
      "commands": ["csharpier"],
      "rollForward": false
    }
  }
}

Put one manifest at the repo root. dotnet tool install, update and uninstall (without -g) edit it for you.

5. Runtime compatibility

A tool targets a runtime, just like any app:

 tool targets net8.0, machine has only the .NET 10 runtime
   rollForward false --> fails: "You must install or update .NET to run this application"
   rollForward true  --> runs on .NET 10 (usually fine, test it)

Install with --allow-roll-forward (or set rollForward in the manifest) when you know the tool works on newer runtimes. With the .NET 10 SDK, tool authors can also ship RID-specific and Native AOT tool packages, which don't need a matching runtime at all.

6. One-shot execution in .NET 10

dnx dotnet-counters --version 9.0.0 ps        # shorthand
dotnet tool exec dotnet-counters --version 9.0.0 ps

It asks before downloading unless you pass --yes, and it downloads through the same NuGet sources and package source mapping as any other package.

7. CI patterns

 1. setup-dotnet from global.json
 2. restore the NuGet cache (key includes .config/dotnet-tools.json)
 3. dotnet tool restore          <-- first, and let it fail loudly
 4. dotnet restore / build / test
 5. dotnet ef migrations bundle  <-- uses the pinned dotnet-ef
 6. dotnet csharpier check .     <-- uses the pinned formatter

Because local tools restore into the NuGet global packages folder, the same cache, nuget.config, authentication and source mapping apply as for package references.

8. Making your own tool

Pack with dotnet pack, push to a feed, and teams install it like any other tool.

9. Security

A tool runs arbitrary code with your permissions and, in CI, with the pipeline's credentials.

• Check the package id and owner carefully; typosquatted names are a real attack.
• Pin versions in the manifest and update them through reviewed pull requests (Dependabot or Renovate understand dotnet-tools.json).
• Restore through an internal feed with package source mapping.
• nuget.org packages are repository-signed; dotnet nuget verify checks signatures, and trustedSigners can require them.

10. .NET 11 awareness

One-shot execution and RID-specific tool packages are new in .NET 10. Watch the .NET 11 SDK notes for further changes to tool execution before relying on them in scripts.

11. Try it yourself

1. In an empty folder run dotnet new tool-manifest and open .config/dotnet-tools.json.
2. Run dotnet tool install dotnet-counters and see the manifest change.
3. Install a different version globally with dotnet tool install -g dotnet-counters --version <other>, then run dotnet counters --version inside and outside the folder.
4. Delete the tool's folder from ~/.nuget/packages, run dotnet counters --version, and read the error. Run dotnet tool restore and try again.
5. Run dotnet tool list and dotnet tool list -g and compare.
6. Run dnx dotnet-dump --help and note the confirmation prompt.
7. Pack the code example's tool project, install it from a local folder with dotnet tool install Contoso.ReleaseNotes --add-source ./artifacts, and run dotnet release-notes.

# GitHub Actions: restore pinned tools before using them
- uses: actions/setup-dotnet@v4
  with:
    global-json-file: global.json

- name: Cache NuGet packages
  uses: actions/cache@v4
  with:
    path: ~/.nuget/packages
    key: nuget-${{ runner.os }}-${{ hashFiles('**/packages.lock.json', '.config/dotnet-tools.json') }}

- name: Restore local tools
  run: dotnet tool restore

- name: Check formatting with a pinned formatter
  run: dotnet csharpier check .

<!-- Making your own tool -->
<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net10.0</TargetFramework>
    <PackAsTool>true</PackAsTool>
    <ToolCommandName>release-notes</ToolCommandName>
    <PackageId>Contoso.ReleaseNotes</PackageId>
    <Nullable>enable</Nullable>
  </PropertyGroup>
</Project>