Install and update the CLI

The CLI is a .NET tool, so it runs anywhere .NET 10 runs: Windows, macOS (Apple silicon and Intel) and Linux. You need the .NET 10 SDK, which includes the ASP.NET Core runtime the CLI uses.

dotnet --version

The command must report a 10.x version. If it reports an older version or is not found, install the SDK for your system from Microsoft’s download page, then open a new terminal.

You do not need a Groundhog account to install the CLI. You need one, or a tunnel’s connection key, to connect an app.

Install the .NET 10 SDK with Microsoft’s Windows installer, or with winget if you use it. Then, in PowerShell or Windows Terminal, run:

dotnet tool install --global Groundhog.Cli --version 0.4.0-preview.7
groundhog --version

The tool goes into %USERPROFILE%\.dotnet\tools, which the .NET installer adds to your PATH. Open a new terminal if groundhog is not found straight away.

Use Windows Terminal for the best result. The older console window works too: Groundhog switches it to UTF-8 while it runs, so its symbols draw correctly, and switches it back when it closes.

Install the .NET 10 SDK with Microsoft’s macOS installer package for your Mac (Arm64 for Apple silicon, x64 for Intel). Then, in Terminal, run:

dotnet tool install --global Groundhog.Cli --version 0.4.0-preview.7
groundhog --version

The tool goes into ~/.dotnet/tools. The macOS installer package adds that folder to your PATH for new terminals. If you installed .NET another way and groundhog is not found, add the folder yourself:

echo 'export PATH="$PATH:$HOME/.dotnet/tools"' >> ~/.zprofile
source ~/.zprofile

Install the .NET 10 SDK from your distribution’s packages or with Microsoft’s install script; Microsoft’s download page lists both for each distribution. Then run:

dotnet tool install --global Groundhog.Cli --version 0.4.0-preview.7
groundhog --version

The tool goes into ~/.dotnet/tools. Most Linux installs do not add that folder to your PATH, so add it to your shell profile once:

echo 'export PATH="$PATH:$HOME/.dotnet/tools"' >> ~/.bashrc
source ~/.bashrc

Use ~/.zshrc instead of ~/.bashrc if your shell is zsh.

To pin the CLI to one repository, so everyone on the project uses the same version, install it as a local tool from the repository’s folder:

dotnet new tool-manifest
dotnet tool install Groundhog.Cli --version 0.4.0-preview.7
dotnet groundhog --version

Commit .config/dotnet-tools.json. Teammates run dotnet tool restore once, then dotnet groundhog. This works the same on Windows, macOS and Linux.

groundhog

In an interactive terminal, groundhog opens a full-screen app. It starts on a launch screen with your version, whether you are signed in and how many of your tunnels are connected. Press Enter to continue, or Q to quit.

Next, use the full-screen app to sign in and see your tunnels, or connect your app with a connection key.

Groundhog checks NuGet for a newer CLI at most once a day, in the background. When one exists, the launch screen shows UPDATE AVAILABLE and the bar at the top of the app shows the new version with press U. Press U, then Y to confirm.

Other commands, such as groundhog host, print a one-line notice instead and run straight away. To update from the command line:

groundhog update --check
groundhog update
groundhog update --yes

Preview installations are offered previews; stable installations are offered stable releases unless you add --prerelease. Your profiles, sign-in and saved keys are kept. Tunnels you are already hosting keep the old version until you restart them.

On macOS and Linux the update installs while Groundhog is open, then asks you to run your command again.

Windows does not let a program replace its own files while it is running. When you update on Windows, Groundhog closes and a small PowerShell window finishes the update a few seconds later, then tells you when to start groundhog again.

Every running copy of Groundhog keeps the old files in use, including another terminal with groundhog open and agents you started in the background with groundhog start. If the update window says it did not complete, close those first:

groundhog ps
groundhog stop myapp
groundhog update

If it still fails, close every Groundhog window and run dotnet tool update --global Groundhog.Cli --version <new version> yourself.

Add --no-update-check to a command, or set GROUNDHOG_NO_UPDATE_CHECK=1, to stop the daily check. groundhog update still works when you run it yourself.

Scripts are not interrupted: redirected output, JSON output, --no-interactive and background agents never check. When NuGet cannot be reached, the check stays quiet and tries again the next day.

Behind a company proxy, both installing and updating need the proxy set in NuGet’s configuration. Ask your IT team for the address.

It holds your saved profiles (profiles.json), your sign-in and saved connection keys (credentials.dat) and the last update check. On Windows the sign-in file is encrypted for your Windows user. On macOS and Linux it is a file only your user can read; Groundhog refuses to use it if its permissions are wider.

Set GROUNDHOG_HOME to use a different folder, for example a separate one for automation.

Sign out first, so the service revokes this computer’s access and the saved keys are removed, then uninstall:

groundhog logout
dotnet tool uninstall --global Groundhog.Cli

For a local tool, run dotnet tool uninstall Groundhog.Cli in the repository instead. To remove saved profiles too, delete Groundhog’s folder. Your tunnels stay in your workspace until you delete them there.

• command not found (macOS or Linux) or is not recognized (Windows): open a new terminal. If that does not help, add the .NET tools folder to your PATH as shown for macOS or Linux, or run dotnet tool list --global to check the tool is installed.
• The SDK is too old: dotnet --version must report 10.x. Install the .NET 10 SDK and try again.
• Symbols show as question marks, or the screen jumps (Windows): update to the current CLI, which switches the console to UTF-8, and use Windows Terminal.

For problems connecting a tunnel, see Troubleshooting your connection.