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

Article
07/27/2023

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.

Use the tool as a global tool

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.
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.
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

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.
```

Invoke the tool:

On Windows:

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

On Linux or macOS:

~/bin/botsay hello from the bot

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.

Install and use local tools

Share via