> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cowboy.inc/llms.txt
> Use this file to discover all available pages before exploring further.

# Install the CLI

> Install the cowboy CLI with Homebrew, a direct binary, or the Python SDK

## Overview

The `cowboy` CLI is a single Rust binary. Pick the method that fits your workflow, then verify with `cowboy version` before starting the [Quickstart](https://docs.cowboy.inc/getting-started/quickstart.md).

**What you'll learn:**

* How to install `cowboy` (and optionally `lasso`) with Homebrew
* How to download and verify a binary directly
* How to install the Python SDK your actors import
* How to enable shell completions

## Homebrew (recommended)

Cowboy publishes a public tap at [`cowboyinc/homebrew-tap`](https://github.com/cowboyinc/homebrew-tap):

```bash theme={null}
brew install cowboyinc/tap/cowboy
```

> [!NOTE]
>
> Homebrew may trail the latest release by a version or two — the formula tracks whichever build the team has last validated for the tap, not every tag pushed to [releases](https://github.com/cowboyinc/cowboy-cli/releases). If you need the newest binary immediately, use the direct download below.

If you use the interactive console, install it the same way:

```bash theme={null}
brew install cowboyinc/tap/lasso
```

## Direct download (macOS/Linux)

Grab your platform's archive from the [`cowboy-cli` releases page](https://github.com/cowboyinc/cowboy-cli/releases), verify its checksum, unpack it, and put the three binaries on your `PATH`.

On Linux, run `uname -m` first: `x86_64` needs the `linux-x64` archive and `aarch64` the `linux-arm64` one.

```bash macOS (Apple Silicon) theme={null}
curl -LO https://github.com/cowboyinc/cowboy-cli/releases/latest/download/cowboy-darwin-arm64.tar.xz
curl -LO https://github.com/cowboyinc/cowboy-cli/releases/latest/download/SHA256SUMS
shasum -a 256 --ignore-missing -c SHA256SUMS
tar -xf cowboy-darwin-arm64.tar.xz
sudo mv cowboy cowboy-dev-runner lasso /usr/local/bin/
```

```bash Linux (x86_64) theme={null}
curl -LO https://github.com/cowboyinc/cowboy-cli/releases/latest/download/cowboy-linux-x64.tar.xz
curl -LO https://github.com/cowboyinc/cowboy-cli/releases/latest/download/SHA256SUMS
sha256sum --ignore-missing -c SHA256SUMS
tar -xf cowboy-linux-x64.tar.xz
sudo mv cowboy cowboy-dev-runner lasso /usr/local/bin/
```

```bash Linux (arm64) theme={null}
curl -LO https://github.com/cowboyinc/cowboy-cli/releases/latest/download/cowboy-linux-arm64.tar.xz
curl -LO https://github.com/cowboyinc/cowboy-cli/releases/latest/download/SHA256SUMS
sha256sum --ignore-missing -c SHA256SUMS
tar -xf cowboy-linux-arm64.tar.xz
sudo mv cowboy cowboy-dev-runner lasso /usr/local/bin/
```

Each release ships one `.tar.xz` archive per platform (`cowboy-darwin-arm64.tar.xz`, `cowboy-linux-arm64.tar.xz`, `cowboy-linux-x64.tar.xz`) and a `SHA256SUMS` file covering them. Each archive holds `cowboy`, the `cowboy-dev-runner` local simulator that `cowboy run` and `cowboy test` use, and `lasso`; keep them together in one directory. On Linux, `tar` needs `xz` (the `xz-utils` package on Debian and Ubuntu). There is no Intel macOS or Windows binary; on Windows, install inside WSL and follow the Linux instructions above.

> [!NOTE]
>
> Release binaries are ad-hoc signed, not notarized, so macOS Gatekeeper will refuse to run one downloaded through a browser (`spctl` reports it as rejected). If you hit "cannot be opened because the developer cannot be verified," clear the quarantine flag before running it:
>
> ```bash theme={null}
> xattr -d com.apple.quarantine /usr/local/bin/cowboy /usr/local/bin/cowboy-dev-runner /usr/local/bin/lasso
> ```

## Python SDK

Actors scaffolded by `cowboy init` import `cowboy_sdk`, published on PyPI as [`cowboy-sdk`](https://pypi.org/project/cowboy-sdk/):

```bash theme={null}
pip install cowboy-sdk
```

> [!NOTE]
>
> The scaffold's `pyproject.toml` pins `cowboy-sdk>=0.1.2`, one version ahead of the `0.1.1` currently on PyPI. Projects created with `cowboy init` use `uv`, so `uv sync` will resolve the pin automatically once `0.1.2` is published — no action needed on your part in the meantime.

## Shell completions

`cowboy completions <shell>` prints a completion script for `bash`, `zsh`, `fish`, `elvish`, or `powershell`.

```bash zsh theme={null}
cowboy completions zsh > "${fpath[1]}/_cowboy"
```

```bash bash theme={null}
cowboy completions bash | sudo tee /etc/bash_completion.d/cowboy > /dev/null
```

Open a new shell afterward to pick up the completions.

## Verify

```bash theme={null}
cowboy version
```

If you installed `lasso`, verify it separately:

```bash theme={null}
lasso --version
```

## Upgrading

```bash Homebrew theme={null}
brew upgrade cowboy
```

```bash Direct download theme={null}
# Re-run the download snippet above — the URLs above always resolve
# to the latest release.
```

## Troubleshooting

> [accordion] 'cowboy: command not found'
>
> The binary isn't on your `PATH`. If you used Homebrew, run `brew --prefix` and confirm that directory's `bin/` is on your `PATH`. If you downloaded a binary directly, confirm you moved it to a directory already on your `PATH` (for example `/usr/local/bin`), then open a new terminal and run `cowboy version`.

> [accordion] macOS blocks the binary with an unidentified developer warning
>
> Release binaries are ad-hoc signed rather than notarized. Clear the quarantine attribute Gatekeeper adds to browser-downloaded files: `xattr -d com.apple.quarantine /usr/local/bin/cowboy /usr/local/bin/cowboy-dev-runner /usr/local/bin/lasso`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.