How to install the Lightdash CLI

The Lightdash CLI is the recommended way to develop your dbt + Lightdash project. It makes development faster and easier, as well as giving you options for building more powerful automation to manage your Lightdash instance.

Installation options

Mac users: We recommend using Homebrew as it’s the easiest installation method and doesn’t require installing Node.js separately.

Windows users: We recommend installing the CLI inside WSL (Windows Subsystem for Linux). WSL gives you a full Linux environment where the Lightdash CLI, Node.js, and dbt all behave the same as they do on macOS and Linux. If you can’t use WSL, follow the PowerShell instructions instead.

Other platforms: Use the NPM installation method, which works across all platforms but requires Node.js to be installed first.

You can also download the CLI binary directly from GitHub releases if you prefer not to use a package manager.

Install via Homebrew

The easiest way to install the Lightdash CLI on Mac is using Homebrew. This method doesn’t require you to install Node.js separately:

brew tap lightdash/lightdash
brew install lightdash

Install via NPM

Before installing Lightdash CLI via NPM, you need to have NodeJS/NPM installed on your machine. To check that, run the following command in your terminal:

node -v; npm -v;
# it should print something like:
# v20.8.0
# 8.15.0

Don't have NodeJS/NPM installed in your system?

We recommend installing NodeJS/NPM using NVM (Node Version Manager) which works for POSIX-compliant shells (sh, dash, ksh, zsh, bash on these platforms: unix, macOS, and windows WSL)

Open your terminal and run the command below to install NVM (Node Version Manager) to your system.

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.2/install.sh | bash
# or
wget -qO- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.2/install.sh | bash

Restart terminal and install NodeJS by running

nvm install --lts

Check that NodeJS is installed by running

node -v

Running the command above should output something like 20.8.0 which means you’ve succesfully installed NodeJS/NPM

---

Alternatively, you can install NodeJS/NPM via your preferred package manager.

Run the following on your terminal to install the Lightdash CLI.

npm install -g @lightdash/cli

If you get an npm ERR! code EACCES error while installing the Lightdash CLI, follow this guide to resolve it.

Install on Windows (WSL, recommended)

The Lightdash CLI doesn’t ship a native Windows binary, and running it directly under PowerShell can hit issues with Node globals, path handling, and dbt. Installing inside WSL avoids all of that — you get a real Linux shell that works exactly like the macOS and Linux setups above.

1. 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). See Microsoft’s WSL install guide if you hit issues.

2. Install Node.js inside WSL

   From your Ubuntu (WSL) terminal, install Node.js via NVM:

   curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.2/install.sh | bash
   

   Close and reopen the terminal, then:

   nvm install --lts
   node -v
   npm -v
   
3. Install the Lightdash CLI

   Still inside WSL:

   npm install -g @lightdash/cli
   lightdash --version
   
4. 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.

Install on Windows (PowerShell)

If you can’t use WSL, you can install the CLI on native Windows via NPM. This path is less well-tested than WSL — if you hit issues with dbt, file paths, or Node globals, switch to WSL.

On locked-down corporate laptops (Zscaler / Netskope / SSL inspection) you’ll likely hit TLS errors on lightdash login and lightdash deploy. Jump to Windows troubleshooting before you start — it covers the corporate CA fix and the Cursor / VS Code agent-terminal gotcha.

1. Install Node.js

   Download the LTS installer from nodejs.org and run it, or install via winget from PowerShell:

   winget install OpenJS.NodeJS.LTS
   

   Open a new PowerShell window and verify:

   node -v
   npm -v
   
2. Install the Lightdash CLI

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

   If lightdash isn’t found after install, close and reopen PowerShell so it picks up the updated PATH.

3. Allow script execution (if needed)

   If PowerShell blocks the lightdash script, allow signed scripts for your user:

   Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned
   

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:

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

or

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.

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

2. 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 npm’s 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 — generate a personal access token in Settings → Personal access tokens and run:

  lightdash login https://app.lightdash.cloud --token <your-token>
  

  Token login doesn’t need a browser callback and 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:

lightdash config set-project

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

Download binary directly

You can also download the CLI binary directly from GitHub releases.

Updating the Lightdash CLI

Update to the latest version

To update your Lightdash CLI to the latest version, run one of the following depending on how you installed it:

Homebrew

brew upgrade lightdash

npm

npm update -g @lightdash/cli

Update to a specific version

Homebrew

Homebrew doesn’t support installing specific versions directly. To install a specific version, use npm instead or download the binary from GitHub releases.

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@0.1743.1

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