How to install the Lightdash CLI

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
Linux (x86_64)	Homebrew
Windows	WSL + Homebrew

If you can’t use Homebrew, you can download the binary directly from GitHub releases. Installing via npm is still supported as an advanced option.

Install via Homebrew

brew tap lightdash/lightdash
brew install lightdash
lightdash --version

Don't have Homebrew installed?

Homebrew runs on macOS and Linux (including WSL). Install it with the one-liner from brew.sh:

/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 for requirements.

Homebrew currently supports macOS (Apple Silicon and Intel) and Linux x86_64. Linux ARM isn’t available yet; use npm there.

Install on Windows (WSL)

The Lightdash CLI doesn’t ship a native Windows binary. Install it inside WSL (Windows Subsystem for Linux), which gives you a real Linux shell where the CLI and dbt behave exactly as they do on macOS and Linux.

Install WSL and Ubuntu

Open PowerShell as Administrator and run:

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).

Install Homebrew inside WSL

From your Ubuntu (WSL) terminal:

/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.

Install the Lightdash CLI

Still inside WSL:

brew tap lightdash/lightdash
brew install lightdash
lightdash --version

Work from your Linux home directory

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:

code .

VS Code will install the WSL extension the first time you do this.

Once WSL is set up, every other guide in these docs — authenticating your CLI, lightdash preview, lightdash 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.

Download binary directly

If you don’t want to use a package manager, download a prebuilt binary from GitHub 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-<version>-macos-arm64.tar.gz — Apple Silicon Macs
lightdash-cli-<version>-macos-x64.tar.gz — Intel Macs
lightdash-cli-<version>-linux-x64.tar.gz — Linux x86_64 (including WSL)

Find your platform

uname -sm
# Darwin arm64   -> macos-arm64
# Darwin x86_64  -> macos-x64
# Linux x86_64   -> linux-x64

Download the matching asset

Pick the version you want from the releases page, then download it (replace <version> and <platform>, e.g. linux-x64):

curl -LO https://github.com/lightdash/lightdash/releases/download/<version>/lightdash-cli-<version>-<platform>.tar.gz

Extract and move it onto your PATH

The archive contains a single binary named lightdash-<platform>:

tar -xzf lightdash-cli-<version>-<platform>.tar.gz
chmod +x lightdash-<platform>
sudo mv lightdash-<platform> /usr/local/bin/lightdash
lightdash --version

Advanced: install via npm

The CLI is also published to npm as @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 (macOS, Linux, WSL) or nodejs.org / winget install OpenJS.NodeJS.LTS (Windows).

npm install -g @lightdash/cli
lightdash --version

If you get an npm ERR! code EACCES error, follow this guide 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.

Windows troubleshooting

These issues come up on locked-down corporate Windows laptops. Try them in order. You’ll see errors like:

FetchError: request to https://app.lightdash.cloud/... failed,
reason: unable to get local issuer certificate

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.

Get your corporate root CA as a .pem file

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.

Point Node at it permanently

In PowerShell, set a user-level environment variable so every new shell picks it up:

[Environment]::SetEnvironmentVariable(
  "NODE_EXTRA_CA_CERTS",
  "C:\Users\<you>\certs\corporate-root.pem",
  "User"
)

Close and reopen your terminal (and Cursor / VS Code) so the variable is picked up. Then retry:

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:

$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:

[Environment]::SetEnvironmentVariable(
  "Path",
  $env:Path + ";C:\Users\<you>\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:

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 instead of OAuth — it doesn’t need a browser callback, which sidesteps most corporate-network OAuth issues.

lightdash config set-project

Pick your project from the list, then re-run lightdash deploy.

Updating the Lightdash CLI

Update to the latest version

brew update
brew upgrade lightdash

npm update -g @lightdash/cli

Update to a specific version

Homebrew
npm

Homebrew doesn’t support installing specific versions directly. To install a specific version, download the binary for that release, or use npm.

To update (or downgrade) to a specific version of the Lightdash CLI, run:

npm install -g @lightdash/cli@VERSION_NUMBER

Replace VERSION_NUMBER with the desired version. For example:

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

Check out the guide on authenticating your CLI tool (login and setup an active project).

​Installation options

​Install via Homebrew

​Install on Windows (WSL)

​Download binary directly

​Advanced: install via npm

​Windows troubleshooting

​unable to get local issuer certificate on lightdash login or deploy

​lightdash: command not found in one terminal but works in another

​Interactive prompts (project picker, OAuth) don’t work inside the Cursor/VS Code agent

​OAuth browser callback never completes

​No active Lightdash project after login

​Updating the Lightdash CLI

​Update to the latest version

​Update to a specific version

​Once you’ve installed the CLI tool, you’ll want to authenticate it

Installation options

Install via Homebrew

Install on Windows (WSL)

Download binary directly

Advanced: install via npm

Windows troubleshooting

`unable to get local issuer certificate` on `lightdash login` or `deploy`

`lightdash: command not found` in one terminal but works in another

Interactive prompts (project picker, OAuth) don’t work inside the Cursor/VS Code agent

OAuth browser callback never completes

`No active Lightdash project` after login

Updating the Lightdash CLI

Update to the latest version

Update to a specific version

Once you’ve installed the CLI tool, you’ll want to authenticate it