> 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 the Terra CLI with Homebrew, npm or your coding agent's plugin, keep it up to date, and set up shell completion.

{% tabs %}
{% tab title="Homebrew" %}
macOS only. The package is a cask, and Homebrew on Linux does not install casks.

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

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

To upgrade:

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

{% endtab %}

{% tab title="npm" %}
Works on macOS, Linux, and Windows. Needs Node.js 18 or later.

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

To upgrade:

```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="Coding agent" %}
If you use Claude Code, Codex or Cursor, install the Terra API plugin instead. When a session starts, the agent checks for the CLI and offers to install it and log you in if either is missing. 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 install:

```bash
terra version
```

The CLI prints a notice when a newer release is available. Set `TERRA_NO_UPDATE_NOTIFIER=1` to turn it off.

## Shell completion

A Homebrew install sets up completion for bash, zsh, and fish. For an 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.