> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/harness-ai/use-harness-cli/harness-cli/install-and-upgrade.md).

# 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 <a href="#what-you-will-learn-in-this-topic" id="what-you-will-learn-in-this-topic"></a>

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 <a href="#before-you-begin" id="before-you-begin"></a>

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 <a href="#install-the-cli" id="install-the-cli"></a>

{% hint style="info" %}
**OPEN SOURCE**

**The Harness CLI is open source.**

* View the source code on [GitHub](https://github.com/harness/cli).
* For the complete list of supported commands, see the [command reference](https://github.com/harness/cli/wiki/Command-Reference).
* Download specific versions from the [releases](https://github.com/harness/cli/releases) page.

We welcome contributions. To report bugs or request features, open an [issue](https://github.com/harness/cli/issues). To contribute code, submit a [pull request](https://github.com/harness/cli/pulls).
{% endhint %}

#### macOS and Linux <a href="#macos-and-linux" id="macos-and-linux"></a>

Run the installer:

```sh
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:

```sh
harness version
```

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

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

#### Windows <a href="#windows" id="windows"></a>

Run the installer in PowerShell:

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

```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 <a href="#homebrew" id="homebrew"></a>

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

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

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

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

***

### Customize the installation <a href="#customize-the-installation" id="customize-the-installation"></a>

Pass installer options after `sh -s --`:

```sh
# 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 <a href="#install-manually" id="install-manually"></a>

If you prefer not to use the installer, download the appropriate release archive from [GitHub Releases](https://github.com/harness/cli/releases), extract the archive, and place the binaries in a directory that is included in your `PATH`.

***

### Upgrade the CLI <a href="#upgrade-the-cli" id="upgrade-the-cli"></a>

The CLI can update itself without rerunning the installer:

```sh
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 <a href="#install-and-upgrade-modules-and-plugins" id="install-and-upgrade-modules-and-plugins"></a>

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.

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

#### Module <a href="#module" id="module"></a>

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

```sh
harness install module har
```

To review what is installed:

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

#### Plugins <a href="#plugins" id="plugins"></a>

```sh
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:

```sh
harness list plugin
harness get plugin <name>
```

***

### Check what an upgrade would do <a href="#check-what-an-upgrade-would-do" id="check-what-an-upgrade-would-do"></a>

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

```sh
harness debug update_check
```

***

### Uninstall the CLI <a href="#uninstall-the-cli" id="uninstall-the-cli"></a>

Remove the binaries:

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

Remove the CLI configuration directory:

```sh
rm -rf ~/.harness
```

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

***

### Next steps <a href="#next-steps" id="next-steps"></a>

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

* [Authenticate](/harness-ai/use-harness-cli/harness-cli/authenticate.md): Log in and set up your first profile.
* [Harness CLI overview](/harness-ai/use-harness-cli/harness-cli/harness-cli-overview.md): Understand the command structure.

{% @harness-feedback/feedback module="harness-ai" pagePath="harness-ai/use-harness-cli/harness-cli/install-and-upgrade" %}