# Install the Levelrail CLI: npm, Homebrew or a Binary

> Three ways to install levelrail-cli: npm or a runner like npx, the Homebrew tap, or a release binary for macOS, Linux and Windows. It is a client only.

Canonical URL: https://levelrail.com/blog/levelrail-cli-install-npm-homebrew-binary/

You can install `levelrail-cli` from npm, from the Homebrew tap, or by downloading a release binary. All three give you the same command line client. It controls an existing Levelrail server and does not install one.

This post lists each route and what to know about it, using the [packages page](https://levelrail.com/packages/), the [install page](https://levelrail.com/install/) and the [CLI reference](https://docs.levelrail.com/cli-reference). If you still need a server, start with [the five minute install](https://levelrail.com/blog/install-levelrail-five-minutes/).

## The CLI is a client

The CLI is a scriptable client for the control plane's HTTP API. Everything it does goes through `/api/v1` with the same tokens and permissions as the dashboard, so you need no SSH key and no open port on your servers.

It never installs the server. The server comes from a Docker image or a GitHub release, as described on [the install page](https://levelrail.com/install/). The install page also notes that nodes must be Linux, while the CLI runs on macOS, Windows and Linux.

## Option 1: npm

The `levelrail-cli` package puts the client on any machine with Node.js. Pick the runner you already use:

```bash
# run once
npx levelrail-cli
yarn dlx levelrail-cli
pnpm dlx levelrail-cli

# or install globally
npm i -g levelrail-cli
```

The package pulls in the one platform package that matches your machine, so you do not install those by hand. The packages page lists them: `levelrail-cli-linux-amd64`, `levelrail-cli-linux-arm64`, `levelrail-cli-darwin-amd64`, `levelrail-cli-darwin-arm64`, `levelrail-cli-windows-amd64` and `levelrail-cli-windows-arm64`.

`levelrail-cli` is published to npm with a provenance attestation, so npm can show which repository and workflow built it.

## Option 2: Homebrew

The tap serves macOS and Linux:

```bash
brew install glincker/tap/levelrail-cli
```

The tap lives at [glincker/homebrew-tap](https://github.com/glincker/homebrew-tap). The CLI reference notes that when a package manager owns the binary, such as Homebrew, `levelrail-cli update` refuses and names the right upgrade command, so upgrade through `brew`.

## Option 3: a release binary

[GitHub Releases](https://github.com/glincker/levelrail/releases) carries CLI binaries for macOS, Linux and Windows, on amd64 and arm64. Each release also lists `checksums.txt` and its cosign bundle.

The installing docs describe an `install-cli.sh` release asset. Download it, check it against `checksums.txt`, then run it:

```bash
curl -fsSLO https://github.com/glincker/levelrail/releases/latest/download/install-cli.sh
curl -fsSLO https://github.com/glincker/levelrail/releases/latest/download/checksums.txt
grep ' install-cli.sh$' checksums.txt | sha256sum -c -  # macOS: shasum -a 256 -c -
sh install-cli.sh
```

For a manual download of a binary, check the checksum before you run it. The verification steps, including cosign, are in [How to verify a Levelrail release](https://levelrail.com/blog/verify-levelrail-release-checksums-cosign/). The docs say Windows is not supported for in-place updates: re-run `install-cli.ps1` there.

## Sign in

Point the CLI at your server and sign in. This is the flow from the CLI reference:

```bash
export APP_API_URL=https://console.example.com
levelrail-cli auth login --device
levelrail-cli auth whoami
```

`--device` prints a short code that you approve in the dashboard. For CI, create an API token under Settings, API tokens and pass it with `--token`, `LEVELRAIL_TOKEN` or `APP_API_TOKEN`.

## Keeping it current

`levelrail-cli update --check` shows the current version and the latest release. `update --yes` replaces the binary after verifying the checksum and the release signature, and the previous binary is kept as `levelrail-cli.bak`. This applies to a binary you installed yourself, not one a package manager owns.

## Which route to choose

Use npm if Node.js is already on the machine and you want `npx` or a global install. Use Homebrew on a Mac or Linux workstation you keep up to date with `brew`. Use a release binary for CI images, air-gapped hosts or anywhere you want to check the checksum and signature yourself. This post does not compare speed or size, since the sources do not.

## FAQ

**Does the CLI install the Levelrail server?** No. It is a client for an existing control plane.

**Which platforms have release binaries?** Linux, macOS and Windows, each on amd64 and arm64.

**How do I authenticate the CLI?** Set `APP_API_URL` and run `levelrail-cli auth login --device`, or pass a token for CI.

## Next steps

See every publishing channel on [the packages page](https://levelrail.com/packages/), the server install on [the install page](https://levelrail.com/install/), and the full command list in the [CLI reference](https://docs.levelrail.com/cli-reference).

## Frequently asked questions

### Does the CLI install the Levelrail server?

No. levelrail-cli is a client for an existing control plane. The server installs from Docker or a GitHub release.

### Which platforms have release binaries?

The packages page lists CLI builds for Linux, macOS and Windows, each on amd64 and arm64.

### How do I authenticate the CLI?

Set APP_API_URL and run levelrail-cli auth login --device, or pass a token with --token, LEVELRAIL_TOKEN or APP_API_TOKEN.
