Tutorial: Install and use a .NET global tool using the .NET CLI

This article applies to: ✔️ .NET Core 2.1 SDK and later versions

This tutorial teaches you how to install and use a global tool. You use a tool that you create in the first tutorial of this series.

Prerequisites

• Complete the first tutorial of this series.
• .NET 10.0.100 SDK or later (for dnx) - optional but recommended.

Run the tool without installation (recommended)

Starting with .NET 10.0.100, you can run .NET tools without permanent installation using dnx:

1. Run the tool directly using dnx (simplified syntax):

   dnx microsoft.botsay --add-source ./nupkg microsoft.botsay hello from the bot
   

   The --add-source parameter tells the .NET CLI to use the ./nupkg directory as an additional source feed for NuGet packages when the tool is not available on NuGet.org.

Use the tool as a global tool (traditional installation)

If you prefer permanent installation for frequent use:

1. Install the tool from the package by running the dotnet tool install command in the microsoft.botsay project folder:

   dotnet tool install --global --add-source ./nupkg microsoft.botsay
   

   The --global parameter tells the .NET CLI to install the tool binaries in a default location that is automatically added to the PATH environment variable.

   The --add-source parameter tells the .NET CLI to temporarily use the ./nupkg directory as an additional source feed for NuGet packages. You gave your package a unique name to make sure that it will only be found in the ./nupkg directory, not on the Nuget.org site.

   The output shows the command used to call the tool and the version installed:

   You can invoke the tool using the following command: botsay
   Tool 'microsoft.botsay' (version '1.0.0') was successfully installed.
   

   Note

   By default the architecture of the .NET binaries to install represents the currently running OS architecture. To specify a different OS architecture, see dotnet tool install, --arch option.

2. Invoke the tool:

   botsay hello from the bot
   

   Note

   If this command fails, you may need to open a new terminal to refresh the PATH.

3. Remove the tool by running the dotnet tool uninstall command:

   dotnet tool uninstall -g microsoft.botsay
   

Use the tool as a global tool installed in a custom location

1. Install the tool from the package.

   On Windows:

   dotnet tool install --tool-path c:\dotnet-tools --add-source ./nupkg microsoft.botsay
   

   On Linux or macOS:

   dotnet tool install --tool-path ~/bin --add-source ./nupkg microsoft.botsay
   

   The --tool-path parameter tells the .NET CLI to install the tool binaries in the specified location. If the directory doesn't exist, it is created. This directory is not automatically added to the PATH environment variable.

   The output shows the command used to call the tool and the version installed:

   You can invoke the tool using the following command: botsay
   Tool 'microsoft.botsay' (version '1.0.0') was successfully installed.
   

2. Invoke the tool:

   On Windows:

   c:\dotnet-tools\botsay hello from the bot
   

   On Linux or macOS:

   ~/bin/botsay hello from the bot
   

3. Remove the tool by running the dotnet tool uninstall command:

   On Windows:

   dotnet tool uninstall --tool-path c:\dotnet-tools microsoft.botsay
   

   On Linux or macOS:

   dotnet tool uninstall --tool-path ~/bin microsoft.botsay
   

Troubleshoot

If you get an error message while following the tutorial, see Troubleshoot .NET tool usage issues.

Next steps

In this tutorial, you installed and used a tool as a global tool. For more information about how to install and use global tools, see Managing global tools. To install and use the same tool as a local tool, advance to the next tutorial.