# Installation

> Get l4 onto a laptop or a CI image with Homebrew, go install or a prebuilt archive, and confirm the install worked.

Source: https://docs.levelfour.ai/cli/installation


Homebrew is the recommended route on macOS and Linux. `go install` needs a Go toolchain. Every [release on GitHub](https://github.com/LevelFourAI/levelfour-cli/releases) also ships static archives:

* Linux: `amd64`, `arm64`
* macOS: `amd64`, `arm64`
* Windows: `amd64`, `arm64`

## Install

| Method           | Binaries installed   | Needs                                   |
| ---------------- | -------------------- | --------------------------------------- |
| Homebrew         | `levelfour` and `l4` | macOS or Linux                          |
| `go install`     | `levelfour` only     | a Go toolchain (1.26.3+)                |
| Prebuilt archive | `levelfour` and `l4` | no toolchain, just download and extract |

**Homebrew**

```bash
brew install LevelFourAI/tap/levelfour
```

The tap ships a single `levelfour` cask, and it installs both binaries: `levelfour` and `l4`. [Two binaries, same tool](/cli#two-binaries-same-tool) covers which name to use.

**go install**

With a Go toolchain (1.26.3+):

```bash
go install github.com/LevelFourAI/levelfour-cli/cmd/levelfour@latest
```

The binary is named `levelfour`. Symlink to `l4` if you want the short form:

```bash
ln -s "$(which levelfour)" "$(dirname "$(which levelfour)")/l4"
```

> **Note**
>
> `go install` builds only `levelfour`. The verify step below and the rest of these docs say `l4`, so make the symlink or substitute the name as you read.

**Prebuilt archive**

Archive naming: `levelfour-cli_<version>_<os>_<arch>.tar.gz` (`.zip` on Windows). Each archive contains both the `levelfour` and `l4` binaries.

```bash
VERSION=0.1.0
curl -L https://github.com/LevelFourAI/levelfour-cli/releases/download/v${VERSION}/levelfour-cli_${VERSION}_linux_amd64.tar.gz \
  | tar xz
sudo mv levelfour l4 /usr/local/bin/
```

Set `VERSION` to the release you want. The example pulls the Linux `amd64` archive.

Checksums for every release are signed under `checksums.txt` on the Release page.

## Verify the installation

```bash
l4 --version
```

```text
l4 version 0.1.0 (commit: 2e84aa4)
```

> **Success**
>
> A version line is the proof: the shell found the binary and it answered. Your version and commit will differ from the example.

## Shell completion

Generate completion scripts for your shell:

**bash**

```bash
source <(l4 completion bash)
# or persist:
l4 completion bash | sudo tee /etc/bash_completion.d/l4 > /dev/null
```

**zsh**

```bash
source <(l4 completion zsh)
# or persist:
l4 completion zsh > "${fpath[1]}/_l4"
```

**fish**

```bash
l4 completion fish | source
# or persist:
l4 completion fish > ~/.config/fish/completions/l4.fish
```

**PowerShell**

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

## Updating

`l4` checks for new versions in the background after each command and prints an update hint to stderr if a newer release is available. To upgrade:

**Homebrew**

```bash
brew upgrade levelfour    # updates both binaries
```

**go install**

```bash
go install github.com/LevelFourAI/levelfour-cli/cmd/levelfour@latest
```

## CI and Docker images

The CLI is a single static Go binary with no runtime dependencies. To pin a version inside a CI image:

```dockerfile title="Dockerfile"
ARG LEVELFOUR_CLI_VERSION=0.1.0
RUN curl -fsSL https://github.com/LevelFourAI/levelfour-cli/releases/download/v${LEVELFOUR_CLI_VERSION}/levelfour-cli_${LEVELFOUR_CLI_VERSION}_linux_amd64.tar.gz \
  | tar xz -C /usr/local/bin levelfour l4
```

For a workflow that runs `l4`, see [CI/CD integration](/guides/ci-cd).

## Next

* [CLI authentication](/cli/authentication) is how `l4` gets a credential, and which commands need a read-write key
* [Commands](/cli/commands/costs) is the per-command reference, starting with `l4 costs`
* [Recipes](/cli/recipes) has the end-to-end shell pipelines