> 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-platform/3.0/harness-cli/cli/install-and-upgrade.md).

# Install and Upgrade

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

{% 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 %}

{% tabs %}
{% tab title="macOS and Linux" %}
Run the installer:

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

```bash
harness version
```

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

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

{% endtab %}

{% tab title="Windows" %}
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.
{% endtab %}

{% tab title="Homebrew" %}
If you use Homebrew on macOS, install the CLI with:

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

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

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

{% endtab %}
{% endtabs %}

### Customize the installation

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

```bash
# 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](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

The CLI can update itself without rerunning the installer:

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

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

#### Module

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

```bash
harness install module har
```

To review what is installed:

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

#### Plugins

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

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

```bash
harness debug update_check
```

### Uninstall the CLI

Remove the binaries:

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

Remove the CLI configuration directory:

```bash
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](https://developer.harness.io/harness-platform/3.0/harness-cli/cli/authenticate-the-harness-cli.md): Log in and set up your first profile.
* [Harness CLI overview](broken://pages/62b9efcd3e69c230559e566e06f130bc51725640): Understand the command structure.
