Step-by-Step Guide: Creating a Global .NET CLI Tool

Are you interested in creating your own command-line tools using .NET? In this blog post, we'll walk you through the process of building a global CLI tool step by step. By the end of this tutorial, you'll have a fully functional tool that you can use from anywhere on your system.

A global CLI tool is a command-line application that can be installed and run from any directory on your system. These tools are useful for automating tasks, enhancing development workflows, or providing quick access to specific functionalities. By creating your own global CLI tool, you can streamline your work processes and potentially share useful utilities with the wider .NET community.

Prerequisites

Before we get started, make sure you have the following installed:

.NET SDK (version 6.0 or later)
Your favorite code editor

Step 1: Create a New Console Application

To begin, open your terminal or command prompt and run the following command to create a new console application:

dotnet new console -n YourToolName.Cli

Replace YourToolName with a suitable name for your tool.

Next, navigate to the newly created project directory:

cd YourToolName.Cli

Step 2: Implement Your Tool's Functionality

Now it's time to bring your tool to life! Open the Program.cs file in your preferred code editor and implement the desired functionality for your CLI tool. Make sure your Main method handles command-line arguments appropriately.

Step 3: Configure the Project for Packaging

To prepare your project for packaging, open the YourToolName.Cli.csproj file and add the following properties inside the <PropertyGroup> tag:

<PackAsTool>true</PackAsTool>
<ToolCommandName>your-tool-command</ToolCommandName>
<PackageOutputPath>./nupkg</PackageOutputPath>

Replace your-tool-command with the desired command name for your tool.

Step 4: Pack the Tool

In the terminal, navigate to your project directory and run the following command to create a NuGet package:

dotnet pack

This command will generate a NuGet package in the nupkg directory.

Step 5: Install the Tool Globally

After packing, you can install the tool globally using the following command:

dotnet tool install --global --add-source ./nupkg YourToolName.Cli

Step 6: Test Your Tool

Open a new terminal window and run your tool using the command name you specified:

your-tool-command [arguments]

If everything is set up correctly, your tool should execute and perform its intended functionality.

Step 7: (Optional) Publish to NuGet

If you want to share your tool with others, you can publish it to NuGet. Here's how:

NuGet is the package manager for .NET, allowing developers to share and consume useful code. Publishing your tool to NuGet makes it easily accessible to other developers, enabling them to install and use your tool with a simple command.

Create an account on nuget.org if you haven't already.
Get your API key from NuGet.
Push your package to NuGet using the following command:

dotnet nuget push ./nupkg/YourToolName.Cli.1.0.0.nupkg --api-key YOUR_API_KEY --source https://api.nuget.org/v3/index.json

Replace YOUR_API_KEY with your actual NuGet API key.

Step 8: Update or Uninstall

To update your tool after making changes and re-packing, run:

dotnet tool update --global YourToolName.Cli

If you want to uninstall the tool, use:

dotnet tool uninstall --global YourToolName.Cli

When updating your tool, it's important to understand semantic versioning. Semantic versioning uses a three-part version number (MAJOR.MINOR.PATCH) to indicate the nature of changes in each release. Increment the MAJOR version for incompatible API changes, the MINOR version for backwards-compatible new features, and the PATCH version for backwards-compatible bug fixes. This helps users understand the impact of updates and allows for smoother version management.

And there you have it! You've successfully created a global CLI tool using .NET. Feel free to experiment and add more functionality to your tool. Happy coding!