> For the complete documentation index, see [llms.txt](https://docs.tryterra.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tryterra.co/developer-tools/terra-cli/installation.md).

# Installation

Install and update the Terra CLI, then set up shell completion.

Choose an installation method:

{% tabs %}
{% tab title="Native Install (Recommended)" %}
Copy and run the command for your platform in your terminal.

**macOS and Linux:**

```bash
curl -fsSL https://cli.tryterra.co/install.sh | sh
```

**Windows PowerShell:**

```powershell
irm "https://cli.tryterra.co/install.ps1" | iex
```

See [Updates](#updates) for automatic updates and upgrading older versions.
{% endtab %}

{% tab title="npm" %}
**macOS, Linux, and Windows:**

Requires Node.js 18 or later.

```bash
npm install -g @tryterra/cli
```

To upgrade with npm:

```bash
npm install -g @tryterra/cli@latest
```

Or run it without installing:

```bash
npx @tryterra/cli version
```

{% hint style="warning" %}
Do not install with `--no-optional` or `--omit=optional`. The wrapper package depends on one optional platform package that carries the binary. Skipping it leaves nothing to run.
{% endhint %}
{% endtab %}

{% tab title="Homebrew" %}
**macOS:**

```bash
brew install tryterra/tap/terra
```

Shell completion for bash, zsh, and fish is installed with it.

To upgrade with Homebrew:

```bash
brew upgrade tryterra/tap/terra
```

{% endtab %}

{% tab title="Coding agent" %}
If you use Claude Code, Codex or Cursor, install the Terra API plugin. When the CLI is missing or logged out, the agent offers to install it and log you in. In Claude Code:

```
/plugin marketplace add tryterra/agent-skills
/plugin install terra@terra
```

See [Agent skills](/developer-tools/agent-skills.md#install) for Codex and Cursor.
{% endtab %}
{% endtabs %}

Check the installation:

```bash
terra version
```

Next, [log in to Terra](/developer-tools/terra-cli/authentication.md).

## Updates

Standalone, global npm, and Homebrew installations update automatically. Eligible commands can start a background check once every four hours. Your command does not wait for the check or installation; subsequent invocations use the updated version. The next invocation reports the update outcome.

To update explicitly:

```bash
terra update
terra version
```

`terra update` uses the original installation method. On Windows, it schedules installation after the command exits. Updates never request elevated permissions. Standalone updates verify signed checksums before replacing the binary.

Coding agents can trigger automatic updates. CI, help, version, and completion commands do not. Project dependencies, npx, and pinned Homebrew installations are not changed automatically. Other installation methods receive manual update instructions.

To control automatic updates:

| Variable                     | Behavior                                              |
| ---------------------------- | ----------------------------------------------------- |
| `TERRA_NO_AUTO_UPDATE=1`     | Keep update notices without installing updates        |
| `TERRA_NO_UPDATE_NOTIFIER=1` | Disable automatic update checks and installs          |
| `DO_NOT_TRACK=1`             | Disable automatic update activity and usage reporting |

These settings do not prevent an explicit `terra update`.

### Upgrade from an older version

`terra update` is available from v0.15.0. To upgrade an older standalone installation, rerun the installer:

```bash
curl -fsSL https://cli.tryterra.co/install.sh | sh
```

For an older npm or Homebrew installation, use the upgrade command in its installation tab above.

## Shell completion

A Homebrew install sets up completion for bash, zsh, and fish. For a native or npm install, generate the script and put it where your shell reads completions.

{% tabs %}
{% tab title="zsh" %}

```bash
mkdir -p ~/.terra
terra completion zsh > ~/.terra/_terra
```

Then in `~/.zshrc`, before `compinit`:

```bash
fpath=(~/.terra $fpath)
autoload -Uz compinit && compinit
```

{% endtab %}

{% tab title="bash" %}

```bash
# macOS, with Homebrew bash-completion
terra completion bash > /usr/local/etc/bash_completion.d/terra

# Linux
terra completion bash > /etc/bash_completion.d/terra
```

{% endtab %}

{% tab title="fish" %}

```bash
terra completion fish > ~/.config/fish/completions/terra.fish
```

{% endtab %}

{% tab title="PowerShell" %}

```powershell
terra completion powershell | Out-String | Invoke-Expression
```

Add this line to your PowerShell profile to make it permanent.
{% endtab %}
{% endtabs %}

## Releases

Every release, with archives, checksums, and signatures, is on [GitHub](https://github.com/tryterra/terra-cli/releases). The [changelog](https://github.com/tryterra/terra-cli/blob/main/CHANGELOG.md) lists what changed in each version.