> ## Documentation Index
> Fetch the complete documentation index at: https://lightdash-codex-docs-value-label-colors.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# How to install the Lightdash CLI
> Install the Lightdash CLI with Homebrew or download the binary directly
## Installation options
We recommend installing the Lightdash CLI with **Homebrew**. It works on macOS, Linux, and Windows (via WSL), ships a self-contained binary, and doesn't require Node.js.
| Platform | Recommended method |
| ------------------------------ | ----------------------------------------- |
| macOS (Apple Silicon or Intel) | [Homebrew](#install-via-homebrew) |
| Linux (x86\_64) | [Homebrew](#install-via-homebrew) |
| Windows | [WSL + Homebrew](#install-on-windows-wsl) |
If you can't use Homebrew, you can [download the binary directly](#download-binary-directly) from GitHub releases. Installing via npm is still supported as an [advanced option](#advanced-install-via-npm).
## Install via Homebrew
```bash theme={null}
brew tap lightdash/lightdash
brew install lightdash
lightdash --version
```
Homebrew runs on macOS and Linux (including WSL). Install it with the one-liner from [brew.sh](https://brew.sh):
```bash theme={null}
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
```
On Linux, follow the "Next steps" the installer prints to add Homebrew to your `PATH`, then open a new shell. See the [Homebrew on Linux docs](https://docs.brew.sh/Homebrew-on-Linux) for requirements.
Homebrew currently supports macOS (Apple Silicon and Intel) and Linux x86\_64. Linux ARM isn't available yet; use [npm](#advanced-install-via-npm) there.
## Install on Windows (WSL)
The Lightdash CLI doesn't ship a native Windows binary. Install it inside [WSL (Windows Subsystem for Linux)](https://learn.microsoft.com/en-us/windows/wsl/install), which gives you a real Linux shell where the CLI and dbt behave exactly as they do on macOS and Linux.
Open **PowerShell as Administrator** and run:
```powershell theme={null}
wsl --install -d Ubuntu
```
Restart your machine when prompted, then launch **Ubuntu** from the Start menu and finish the first-time user setup (username + password).
From your **Ubuntu (WSL) terminal**:
```bash theme={null}
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
```
Follow the "Next steps" the installer prints to add Homebrew to your `PATH`, then close and reopen the terminal.
Still inside WSL:
```bash theme={null}
brew tap lightdash/lightdash
brew install lightdash
lightdash --version
```
Clone repos and run `lightdash` commands from your WSL home directory (e.g. `~/projects`), **not** from `/mnt/c/...`. File watching, permissions, and dbt are all significantly faster on the Linux filesystem.
You can open a WSL folder in VS Code with:
```bash theme={null}
code .
```
VS Code will install the [WSL extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-wsl) the first time you do this.
Once WSL is set up, every other guide in these docs — [authenticating your CLI](/workflow/cli/authenticate), [`lightdash preview`](/workflow/preview-projects), [`lightdash deploy`](/workflow/cli/deploy) — works exactly as written for macOS/Linux. Just run the commands in your Ubuntu terminal.
On locked-down corporate laptops (Zscaler / Netskope / SSL inspection) you may hit TLS errors on `lightdash login` and `lightdash deploy`. See [Windows troubleshooting](#windows-troubleshooting).
## Download binary directly
If you don't want to use a package manager, download a prebuilt binary from [GitHub releases](https://github.com/lightdash/lightdash/releases). Binaries bundle their own Node.js runtime, so **you don't need Node installed**.
Each release publishes these assets, named for the release version:
* `lightdash-cli--macos-arm64.tar.gz` — Apple Silicon Macs
* `lightdash-cli--macos-x64.tar.gz` — Intel Macs
* `lightdash-cli--linux-x64.tar.gz` — Linux x86\_64 (including WSL)
```bash theme={null}
uname -sm
# Darwin arm64 -> macos-arm64
# Darwin x86_64 -> macos-x64
# Linux x86_64 -> linux-x64
```
Pick the version you want from the [releases page](https://github.com/lightdash/lightdash/releases), then download it (replace `` and ``, e.g. `linux-x64`):
```bash theme={null}
curl -LO https://github.com/lightdash/lightdash/releases/download//lightdash-cli--.tar.gz
```
The archive contains a single binary named `lightdash-`:
```bash theme={null}
tar -xzf lightdash-cli--.tar.gz
chmod +x lightdash-
sudo mv lightdash- /usr/local/bin/lightdash
lightdash --version
```
## Advanced: install via npm
The CLI is also published to npm as [`@lightdash/cli`](https://www.npmjs.com/package/@lightdash/cli). Use this if you need a platform Homebrew doesn't cover (Linux ARM, native Windows PowerShell), want to pin a specific version, or are installing in CI where Node is already present.
You need Node.js 24 or newer. Check with `node -v`, or install it via [NVM](https://github.com/nvm-sh/nvm#install--update-script) (macOS, Linux, WSL) or [nodejs.org](https://nodejs.org/en/download) / `winget install OpenJS.NodeJS.LTS` (Windows).
```bash theme={null}
npm install -g @lightdash/cli
lightdash --version
```
If you get an `npm ERR! code EACCES` error, [follow this guide](https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally) to resolve it. On native Windows, if `lightdash` isn't found after install, close and reopen PowerShell so it picks up the updated `PATH`; if PowerShell blocks the script, run `Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned`.
Native Windows (PowerShell) via npm is less well-tested than WSL. If you hit issues with dbt, file paths, or Node globals, switch to [WSL](#install-on-windows-wsl).
## Windows troubleshooting
These issues come up on locked-down corporate Windows laptops. Try them in order.
### `unable to get local issuer certificate` on `lightdash login` or `deploy`
You'll see errors like:
```text theme={null}
FetchError: request to https://app.lightdash.cloud/... failed,
reason: unable to get local issuer certificate
```
or
```text theme={null}
OAuth failed due to corporate SSL (Zscaler / Netskope / etc.)
```
This is your corporate proxy (Zscaler, Netskope, ZIA, a Palo Alto firewall, etc.) doing TLS inspection — Node.js doesn't trust the intercepting certificate. Fix it by pointing Node at your company CA bundle.
Ask IT for the company root CA certificate as a `.pem` (or `.crt`) file. You can often export it yourself from Windows: run `certmgr.msc`, find the Zscaler / corporate root under **Trusted Root Certification Authorities**, then **All Tasks → Export → Base-64 encoded X.509 (.CER)** and rename to `.pem`.
In **PowerShell**, set a user-level environment variable so every new shell picks it up:
```powershell theme={null}
[Environment]::SetEnvironmentVariable(
"NODE_EXTRA_CA_CERTS",
"C:\Users\\certs\corporate-root.pem",
"User"
)
```
Close and reopen your terminal (and Cursor / VS Code) so the variable is picked up. Then retry:
```powershell theme={null}
lightdash login https://app.lightdash.cloud
```
**Last-resort workaround only:** if you cannot get the CA file, you can run a single command with TLS verification disabled:
```powershell theme={null}
$env:NODE_TLS_REJECT_UNAUTHORIZED=0; lightdash login https://app.lightdash.cloud
```
This disables certificate verification for that shell session and is insecure — use it only to confirm the issue is the corporate proxy, then set `NODE_EXTRA_CA_CERTS` for the real fix. Never bake this into scripts or CI.
### `lightdash: command not found` in one terminal but works in another
Different terminals inside the same editor can use different shells (Git Bash, PowerShell, WSL, or the Cursor / VS Code agent sandbox), and each has its own `PATH`.
* Check where `lightdash` actually lives: `where lightdash` (PowerShell) or `which lightdash` (Bash / WSL).
* If you installed with npm and its global bin isn't on `PATH`, add it. Find it with `npm config get prefix`, then in PowerShell:
```powershell theme={null}
[Environment]::SetEnvironmentVariable(
"Path",
$env:Path + ";C:\Users\\AppData\Roaming\npm",
"User"
)
```
* Close **all** terminals (and the editor) and reopen so the new `PATH` takes effect.
### Interactive prompts (project picker, OAuth) don't work inside the Cursor/VS Code agent
The AI agent's built-in terminal is a non-interactive sandbox — `lightdash login` and the "select a project" arrow-key prompt from `lightdash deploy` can hang or get skipped there.
Run these commands in a **regular terminal tab** (open one via the `+` icon in the terminal pane, not the agent chat), or in WSL / PowerShell directly:
```bash theme={null}
lightdash login https://app.lightdash.cloud
lightdash config set-project # pick your project non-interactively later if needed
lightdash deploy
```
### OAuth browser callback never completes
If clicking the OAuth link opens Lightdash in the browser but the CLI keeps waiting:
* Your corporate proxy may be blocking the callback to `localhost`. Try again on a personal network / hotspot to confirm.
* Or use [token-based login](/workflow/cli/authenticate#login) instead of OAuth — it doesn't need a browser callback, which sidesteps most corporate-network OAuth issues.
### `No active Lightdash project` after login
Login and project selection are separate steps. After `lightdash login` succeeds, set the active project:
```bash theme={null}
lightdash config set-project
```
Pick your project from the list, then re-run `lightdash deploy`.
## Updating the Lightdash CLI
### Update to the latest version
```bash Homebrew theme={null}
brew update
brew upgrade lightdash
```
```bash npm theme={null}
npm update -g @lightdash/cli
```
### Update to a specific version
Homebrew doesn't support installing specific versions directly. To install a specific version, [download the binary](#download-binary-directly) for that release, or use npm.
To update (or downgrade) to a specific version of the Lightdash CLI, run:
```bash theme={null}
npm install -g @lightdash/cli@VERSION_NUMBER
```
Replace `VERSION_NUMBER` with the desired version. For example:
```bash theme={null}
npm install -g @lightdash/cli@2.223.0
```
Your Lightdash CLI version should match the version of Lightdash you see in the UI (scroll to the bottom of your screen to find it). You can check your current CLI version by running `lightdash --version`.
## Once you've installed the CLI tool, [you'll want to authenticate it](/workflow/cli/authenticate)
[Check out the guide on authenticating your CLI tool ](/workflow/cli/authenticate)(login and setup an active project).