> ## Documentation Index
> Fetch the complete documentation index at: https://lightdash-mintlify-6c92035e.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](/guides/cli/cli-authentication), [`lightdash preview`](/guides/cli/how-to-use-lightdash-preview), [`lightdash deploy`](/guides/cli/how-to-use-lightdash-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 instead of OAuth — generate a personal access token in **Settings → Personal access tokens** and run:

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

```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>
  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](/guides/cli/cli-authentication)

[Check out the guide on authenticating your CLI tool ](/guides/cli/cli-authentication)(login and setup an active project).