> ## Documentation Index
> Fetch the complete documentation index at: https://lightdash-refactor-full-audit-reorg.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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)](#install-on-windows-wsl-recommended). 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](#install-on-windows-powershell) instead.

**Other platforms:** Use the [NPM installation method](#install-via-npm), 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.

<Frame>
  <iframe width="100%" height="420" src="https://www.loom.com/embed/4b50ff5f986f4808ad0a2527eabfdaad" frameborder="0" webkitallowfullscreen mozallowfullscreen allowfullscreen />
</Frame>

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

```bash theme={null}
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:

```bash theme={null}
node -v; npm -v;
# it should print something like:
# v20.8.0
# 8.15.0
```

<Accordion title="Don't have NodeJS/NPM installed in your system?">
  We recommend installing NodeJS/NPM using [NVM (Node Version Manager)](https://github.com/nvm-sh/nvm#install--update-script) 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.

  ```bash theme={null}
  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

  ```bash theme={null}
  nvm install --lts
  ```

  Check that NodeJS is installed by running

  ```bash theme={null}
  node -v
  ```

  Running the command above should output something like `20.8.0` which means you've succesfully installed NodeJS/NPM <Icon icon="party-horn" iconType="solid" />

  ***

  Alternatively, you can [install NodeJS/NPM via your preferred package manager](https://nodejs.org/en/download/package-manager).
</Accordion>

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

```bash theme={null}
npm install -g @lightdash/cli
```

<Info>
  If you get an `npm ERR! code EACCES` error while installing the Lightdash CLI, [follow this guide](https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally) to resolve it.
</Info>

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

<Steps>
  <Step title="Install WSL and Ubuntu">
    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). See Microsoft's [WSL install guide](https://learn.microsoft.com/en-us/windows/wsl/install) if you hit issues.
  </Step>

  <Step title="Install Node.js inside WSL">
    From your **Ubuntu (WSL) terminal**, install Node.js via NVM:

    ```bash theme={null}
    curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.2/install.sh | bash
    ```

    Close and reopen the terminal, then:

    ```bash theme={null}
    nvm install --lts
    node -v
    npm -v
    ```
  </Step>

  <Step title="Install the Lightdash CLI">
    Still inside WSL:

    ```bash theme={null}
    npm install -g @lightdash/cli
    lightdash --version
    ```
  </Step>

  <Step title="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:

    ```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.
  </Step>
</Steps>

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

## 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](#install-on-windows-wsl-recommended).

<Info>
  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](#windows-troubleshooting) before you start — it covers the corporate CA fix and the Cursor / VS Code agent-terminal gotcha.
</Info>

<Steps>
  <Step title="Install Node.js">
    Download the **LTS** installer from [nodejs.org](https://nodejs.org/en/download) and run it, or install via winget from PowerShell:

    ```powershell theme={null}
    winget install OpenJS.NodeJS.LTS
    ```

    Open a new PowerShell window and verify:

    ```powershell theme={null}
    node -v
    npm -v
    ```
  </Step>

  <Step title="Install the Lightdash CLI">
    ```powershell theme={null}
    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`.
  </Step>

  <Step title="Allow script execution (if needed)">
    If PowerShell blocks the `lightdash` script, allow signed scripts for your user:

    ```powershell theme={null}
    Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned
    ```
  </Step>
</Steps>

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

<Steps>
  <Step title="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`.
  </Step>

  <Step title="Point Node at it permanently">
    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\<you>\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
    ```
  </Step>
</Steps>

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

### `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:

  ```powershell theme={null}
  [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:

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

## Download binary directly

You can also download the CLI binary directly from [GitHub releases](https://github.com/lightdash/lightdash/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:

<Tabs>
  <Tab title="Homebrew">
    ```bash theme={null}
    brew upgrade lightdash
    ```
  </Tab>

  <Tab title="npm">
    ```bash theme={null}
    npm update -g @lightdash/cli
    ```
  </Tab>
</Tabs>

### Update to a specific version

<Tabs>
  <Tab title="Homebrew">
    Homebrew doesn't support installing specific versions directly. To install a specific version, use npm instead or download the binary from [GitHub releases](https://github.com/lightdash/lightdash/releases).
  </Tab>

  <Tab title="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@0.1743.1
    ```
  </Tab>
</Tabs>

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

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