dotnet-tool

Install a global tool (don't use --global for local tools)

$ dotnet tool install [[-g|--global]] [dotnetsay]

$ dotnet tool restore

$ dotnet tool update [[-g|--global]] [tool_name]

$ dotnet tool uninstall [[-g|--global]] [tool_name]

$ dotnet tool list [[-g|--global]]

$ dotnet tool search [search_term]

$ dotnet tool [[-h|--help]]

dotnet tool <COMMAND> [options] [arguments]

Available Commands:
  install <PACKAGE_ID> [options]
  update <PACKAGE_ID> [options]
  uninstall <PACKAGE_ID> [options]
  list [options]
  run <TOOL_COMMAND_NAME> [arguments]
  search <SEARCH_TERM> [options]

install <PACKAGE_ID>
    Installs a .NET tool specified by its NuGet package ID from NuGet.org or a custom NuGet source.

update <PACKAGE_ID>
    Updates an already installed .NET tool to its latest stable version or a specified version.

uninstall <PACKAGE_ID>
    Removes an installed .NET tool from the system or project.

list
    Displays a list of all currently installed .NET tools, either global or local, based on the provided options.

run <TOOL_COMMAND_NAME>
    Executes a local tool. The TOOL_COMMAND_NAME is the command alias of the tool as defined in its package or manifest.

search <SEARCH_TERM>
    Searches for .NET tools available on NuGet.org that match the specified search term.

-g, --global
    Specifies that the operation applies to global tools, which are available across the system.

-l, --local
    Specifies that the operation applies to local tools, managed within a project's context via a tool manifest file.

--tool-path <PATH>
    Defines a custom directory where global tools should be installed or found. If used, the tool is only accessible via this path.

--add-source <SOURCE>
    Adds an additional NuGet package source to be used during tool installation or search operations.

--configfile <FILE>
    Specifies the path to a custom NuGet configuration file (e.g., nuget.config) to be used.

--framework <FRAMEWORK>
    Specifies the target framework for which the tool should be installed (e.g., net6.0, net8.0).

--version <VERSION>
    Specifies the exact version of the tool to install or update to. Accepts NuGet version ranges.

--verbosity <LEVEL>
    Sets the verbosity level of the command's output. Options include q[uiet], m[inimal], n[ormal], d[etailed], and diag[nostic].

--no-cache
    Prevents caching of packages and HTTP requests, forcing a fresh download.

--prerelease
    Allows installation or search to include prerelease versions of tools.

The dotnet tool command is an integral part of the .NET SDK, designed to manage .NET tools. A .NET tool is essentially a special NuGet package containing a console application, extending the capabilities of the .NET CLI. These tools can be custom-developed or community-contributed utilities that simplify various development and operational tasks.

Tools can be installed in two primary ways: as global tools, making them available system-wide via the shell's PATH, or as local tools, which are scoped to a specific project directory and managed through a tool manifest file (dotnet-tools.json). The dotnet tool command provides the necessary functionalities to install, update, uninstall, list, run, and search for these tools, thereby enhancing developer productivity and ensuring consistent development environments.

• Installing global tools might require elevated permissions (e.g., sudo) if the default installation directory (often ~/.dotnet/tools on Linux/macOS) is not user-writable or if a custom --tool-path outside user control is specified.
• For global tools to be directly executable by their command name, the tool installation directory must be included in your system's PATH environment variable.
• Operations involving local tools (using --local) require a dotnet-tools.json manifest file. If it doesn't exist, dotnet tool install --local will create one in the current directory.
• Command name conflicts can occur if multiple global tools or a global and a local tool share the same command alias. Careful management of installation scopes or aliases might be necessary.

Tool manifests are JSON files, typically named dotnet-tools.json, that reside in a project's root or a parent directory. They serve as a declarative list of local tools and their specific versions required for that project. When you install a local tool, this file is updated. Running dotnet tool restore reads this manifest and installs all listed tools, ensuring everyone working on the project uses the exact same versions of development utilities.

By default, global tools are installed into a user-specific directory. On Linux and macOS, this location is commonly ~/.dotnet/tools. For these tools to be callable directly from any directory, this path must be added to the system's PATH environment variable. The .NET SDK installer usually attempts to configure this environmental variable automatically during installation.

The concept of .NET tools was first introduced with .NET Core 2.1, primarily supporting global tools. A significant enhancement arrived with .NET Core 3.0, which added support for local tools and the associated tool manifest (dotnet-tools.json). This crucial development aimed to make tool dependencies more consistent and reproducible across different development environments and team members, mimicking similar patterns found in other language ecosystems like npm or pipenv. Subsequent .NET versions have continued to refine the tool management experience, focusing on reliability and performance.

dotnet(1), dotnet-build(1), dotnet-run(1), nuget(1)