Install and upgrade the Harness CLI

Install the Harness CLI on macOS, Linux, or Windows, upgrade to new versions, and uninstall cleanly.

The Harness CLI is distributed as a self-contained binary for macOS, Linux (amd64 and arm64), and Windows. This guide explains how to install, upgrade, and uninstall the CLI.

---

What you will learn in this topic

By the end of this guide, you will be able to:

• Install the Harness CLI on macOS, Linux, or Windows using the automated installer, Homebrew, or a release archive.

• Customize the installation for CI/CD systems, containers, and non-standard installation paths.

• Upgrade to the latest release or install a specific version.

• Install or upgrade an individual module or external plugin.

• Inspect what an in-place upgrade would do before you run it.

• Install or upgrade CLI modules and plugins.

• Remove the CLI and its local configuration.

---

Before you begin

Make sure you have:

• macOS, Linux (amd64 or arm64), or Windows.

• Bash or Zsh (macOS/Linux), or PowerShell (Windows).

• Network access to download binaries and release metadata.

---

Install the CLI

OPEN SOURCE

The Harness CLI is open source.

• View the source code on GitHub.

• For the complete list of supported commands, see the command reference.

• Download specific versions from the releases page.

We welcome contributions. To report bugs or request features, open an issue. To contribute code, submit a pull request.

macOS and Linux

Run the installer:

curl -fsSL https://raw.githubusercontent.com/harness/cli/main/install.sh | sh

The installer:

• Installs the harness and harness-har binaries to ~/.local/bin.

• Adds the installation directory to your PATH if necessary.

• Configures shell completions for supported shells.

Verify the installation:

harness version

If the harness command is not available immediately after installation, restart your shell or reload your shell configuration:

source ~/.zshrc
# or
source ~/.bashrc

Windows

Run the installer in PowerShell:

irm https://raw.githubusercontent.com/harness/cli/main/install.ps1 | iex

The installer places the binaries in %LOCALAPPDATA%\Programs\harness and optionally adds them to PATH.

To customize the installation in PowerShell:

# Non-interactive install
$env:HARNESS_NONINTERACTIVE=1; irm https://raw.githubusercontent.com/harness/cli/main/install.ps1 | iex

# Core binary only, non-interactive
$env:HARNESS_NONINTERACTIVE=1; $env:HARNESS_CORE_ONLY=1; irm https://raw.githubusercontent.com/harness/cli/main/install.ps1 | iex

Windows installer flags: -InstallDir, -Version, -Core, -NonInteractive, -NoVerify.

For air-gapped or mirrored environments, set HARNESS_INSTALL_BASE_URL to point the Windows installer at an internal mirror before running it.

Homebrew

If you use Homebrew on macOS, install the CLI with:

brew install --cask harness/tap/harness-cli

This installs the core binary only. To upgrade a Homebrew installation:

brew upgrade --cask harness/tap/harness-cli

---

Customize the installation

Pass installer options after sh -s --:

# Install only the core CLI
curl -fsSL https://raw.githubusercontent.com/harness/cli/main/install.sh | \
  sh -s -- --core

# Install to a custom location without prompts
curl -fsSL https://raw.githubusercontent.com/harness/cli/main/install.sh | \
  sh -s -- --non-interactive --install-dir /usr/local/bin

Flag	Description
--install-dir <path>	Installs the binaries to a custom directory.
--core	Installs only the harness binary.
--non-interactive	Suppresses prompts for automated environments such as CI/CD pipelines and containers.
--no-verify	Skips checksum verification after download.

---

Install manually

If you prefer not to use the installer, download the appropriate release archive from GitHub Releases, extract the archive, and place the binaries in a directory that is included in your PATH.

---

Upgrade the CLI

The CLI can update itself without rerunning the installer:

harness install cli                    # upgrade to latest
harness install cli --version v1.2.3  # install a specific version
harness install cli --check           # print the resolved version without installing
harness install cli --force           # reinstall even if already up to date
harness install cli --core-only       # upgrade core binary only, skip module updates

Flag	Description
--version <v>	Version to install. Defaults to latest.
--install-dir <path>	Directory to install the core binary into. Defaults to ~/.local/bin. Must match where the currently running harness binary lives — if it does not, the command exits with an error rather than installing a second copy elsewhere.
--force	Install even if the current version is already up to date.
--check	Print the resolved version without installing. Exits 1 if the version is not found.
--core-only	Upgrade the core binary only and skip module updates.

---

Install and upgrade modules and plugins

The Harness CLI is built around installable modules (first-party) and plugins (third-party or custom). Use harness install module and harness install plugin to manage them. Modules and external plugins ship as separate binaries that harness dispatches to transparently.

harness install cli upgrades the harness binary and every installed module in one shot. Add --core-only to upgrade the core binary and leave the modules untouched.

harness install module <module_name>
harness install plugin <plugin_name>

Module

For example, install the Artifact Registry module on its own:

harness install module har

To review what is installed:

harness list module
harness list plugin
harness get plugin <plugin_name>

Plugins

harness install plugin har                                 # by name
harness install plugin harness/cli                         # GitHub org/repo
harness install plugin https://example.com/my-plugin.tar.gz  # remote URL
harness install plugin ./my-plugin.tar.gz                  # local archive
harness install plugin all                                 # reinstall all installed plugins

List and inspect installed plugins:

harness list plugin
harness get plugin <name>

---

Check what an upgrade would do

Probe the release manifest and report the actions an in-place upgrade would take, without changing anything on disk.

harness debug update_check

---

Uninstall the CLI

Remove the binaries:

rm "$(command -v harness)" "$(command -v harness-har)" 2>/dev/null

Remove the CLI configuration directory:

rm -rf ~/.harness

Removing the configuration directory also deletes saved profiles, credentials, and CLI settings.

---

Next steps

With the CLI installed, log in and set up a profile before you run your first command.

• Authenticate: Log in and set up your first profile.

• Harness CLI overview: Understand the command structure.