Lightdash CLI reference

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

---

Global options

There are three global options that can be used with any Lightdash CLI command: version, help, and verbose.

Version

--version or -V

Ignores the preceding command and shows the installed CLI version. Usually it's used right after lightdash, like this:

lightdash --version

Help

--help or -h

Tells you what the preceding command does and lists all command-specific options. You can view the Lightdash CLI help like this:

lightdash --help

That returns the Lightdash CLI help menu:

When you use the --help or -h option with a speific command:

lightdash validate -h

That returns details and examples for the command itself:

Verbose

--verbose

Defaults to OFF. When included, each step will print logs as it progresses through the command. For example, here's a --verbose version of lightdash generate-exposures:

Commands

The table below includes a complete list of all commands available in the Lightdash CLI.

For examples and command-specific options, click through the command in the table for docs, or install the Lightdash CLI and use the global help option.

Command	Description
login	Log in to a Lightdash instance using email/password or a token
config set-project	Choose or set the Lightdash project you are working on
compile	Compile lightdash resources using your local project files
preview	Create a temporary preview project, then wait for a keypress to stop
start-preview	Create a preview project that stays open until it is stopped
stop-preview	Shut down an open preview project
deploy	Compile and deploy a Lightdash project using your local project and credentials
refresh	Refresh Lightdash project with remote repository
validate	Validates content from your active project against your local project files
generate	Generates or updates schema.yml file(s) for the selected model(s)
generate-exposures	[Experimental command] Generates a .yml file for Lightdash exposures
dbt run	Executes dbt run, then lightdash generate to add/update schema.yml files
download	Downloads all charts and dashboards from your Lightdash project as code
upload	Uploads all updates to charts and dashboards as code to your Lightdash project

---

lightdash login

Log in to a Lightdash instance using email and password or a token.

lightdash login [URL]

Argument:

• [URL]
  • The URL for your Lightdash instance (see examples below)

Options:

• --token
  • For logging in with an access token (common for SSO users)
  • Exclude this to log in with email and password

Examples:

Log in to Lightdash Cloud US instance (for most Starter customers):

lightdash login https://app.lightdash.cloud

Log in to Lightdash Cloud EU instance while showing detailed logs of login process:

lightdash login https://eu1.lightdash.cloud --verbose

Log in to a custom domain with a personal access token (exclude --token to log in with email and password):

lightdash login https://custom.lightdash.domain --token bv6105f53cb127087189cfib180a3131

lightdash config set-project

Choose the project you're developing in so the CLI knows which project content to look at for other commands like lightdash validate and lightdash preview. If your organization only has one project you won't need to use this!

lightdash config set-project

This command will bring up an interactive list of projects in your organization to choose from.

If you need to set the project non-interactively, you can use one of the two optional arguments below.

Options:

• --name
  • Set the project non-interactively by passing an explicit project name
• --uuid
  • Set the project non-interactively by passing an explicit project UUID

Examples:

Set project to "Healthcare Demo":

lightdash config set-project --name "Healthcare Demo"

Set project to the one with this UUID:

lightdash config set-project --uuid "d75379bc-f6e9-4e52-86b2-d897cabacd0c"

lightdash compile

Compile Lightdash resources using your local project and database credentials. dbt gets compiled first, then your Lightdash explores. If you use dbt node selection to only compile a subset of models, Lightdash will also compile models joined to those models to ensure no field references are broken.

All standard dbt options work with lightdash compile.

Examples:

Compile the whole project:

lightdash compile

Compile only the accounts dbt model, then your Lightdash explores:

lightdash compile -s accounts

Compile your project using the production profile from your local profiles.yml file:

lightdash compile --profile production

lightdash preview

Spin up a temporary preview project using your local project files and content (charts and dashboards) copied from your selected project.

All standard dbt options work with lightdash preview.

Options:

• --name [preview name]
  • Custom name for the preview project. If a name is not provided, a unique, randomly generated name will be created.
• --start-of-week [number]
  • Specifies the first day of the week (used by week-related date functions).
  • 0 (Monday) to 6 (Sunday)
• --skip-dbt-compile
  • (default: false)
  • Skip dbt compile and deploy from the existing ./target/manifest.json
• --skip-warehouse-catalog
  • (default: false)
  • Skip fetch warehouse catalog and use types defined in the YAML.
• --use-dbt-list [true/false]
  • (default: true)
  • Use dbt list instead of dbt compile to generate dbt manifest.json
• --ignore-errors
  • (default: false)
  • Allows deploy with errors on compile

Examples:

Create a temporary preview project with the name PR: Add Revenue Metric and ignore validation errors while spinning it up:

lightdash preview --name "PR: Add Revenue Metric" --ignore errors

Create a temporary preview project with a random name and set the start of week to Monday, only include models with the dbt tag of marketing:

lightdash preview --start-of-week=0 --select "tag:marketing"

lightdash start-preview

Create a persistent preview project using your local project files and content (charts and dashboards) copied from your selected project.

All standard dbt options work with lightdash start-preview.

Required argument:

• --name [preview name]
  • Name for the preview project. If a preview project with this name already exists, it will be updated, otherwise it will create a new preview project.

Options:

• --start-of-week [number]
  • Specifies the first day of the week (used by week-related date functions).
  • 0 (Monday) to 6 (Sunday)
• --skip-dbt-compile
  • (default: false)
  • Skip dbt compile and deploy from the existing ./target/manifest.json
• --skip-warehouse-catalog
  • (default: false)
  • Skip fetch warehouse catalog and use the types defined in YAML
• --use-dbt-list [true/false]
  • (default: true)
  • Use dbt list instead of dbt compile to generate dbt manifest.json
• --ignore-errors
  • (default: false)
  • Allows deploy with errors on compile

lightdash stop-preview

Shuts down a project that was created with lightdash start-preview.

This command does not support using dbt options.

Required argument:

• --name [preview name]
  • Name of the preview project to be deleted.

Example:

Shut down the preview project named neon unicorn.

lightdash stop-preview "neon unicorn"

lightdash deploy

Compiles and deploys the current project to your selected Lightdash Cloud project.

danger

This command is usually used in Github Actions or other deploy scripts. It is not common practice to use lightdash deploy to push your local changes up to Lightdash Cloud outside of your initial project creation.

All standard dbt options work with lightdash deploy.

Options:

• --create [project_name]
  • Create a new project. If a project name is not provided, you'll be prompted for one on creation.
• --ignore-errors
  • (default: false)
  • Allows deploy with errors on compile.
• --start-of-week [number]
  • Specifies the first day of the week (used by week-related date functions).
  • 0 (Monday) to 6 (Sunday)
• --skip-dbt-compile
  • (default: false)
  • Skip dbt compile and deploy from the existing ./target/manifest.json.
• --skip-warehouse-catalog
  • (default: false)
  • Skip fetch warehouse catalog and use types defined in the YAML.
• --use-dbt-list [true|false]
  • (default: true)
  • Use dbt list instead of dbt compile to generate dbt manifest.json.

lightdash refresh

Refreshes your hosted Lightdash project using the latest code from your linked Github repository. This is equivalent to pressing Refresh dbt in the UI as an admin.

This command does not support using dbt options.

lightdash validate

Validates a project by comparing the content in your currently selected project against your local project files. Returns all charts and dashboards that have errors.

All standard dbt options work with lightdash validate.

Options:

• --project [project uuid]
  • Project UUID to validate, if not provided, the last preview will be used
• --preview
  • (default: false)
  • Validate the last preview if available.
• --skip-dbt-compile
  • (default: false)
  • Skip dbt compile and deploy from the existing ./target/manifest.json.
• --skip-warehouse-catalog
  • (default: false)
  • Skip fetch warehouse catalog and use types defined in the YAML.
• --use-dbt-list [true/false]
  • (default: true)
  • Use dbt list instead of dbt compile to generate dbt manifest.json.
• --only [elems...]
  • (default: ["charts","dashboards","tables"])
  • Specify project elements to validate.

Example:

Validate only dashboards and use the existing compiled dbt manifest:

lightdash validate --only ["dashboards"] --skip-dbt-compile

lightdash generate

Generates a new schema.yml file or updates existing schema.yml for selected model(s).

All standard dbt options work with lightdash generate.

Options:

• -y or --assume-yes
  • (default: false)
  • assume yes to prompts
• --exclude-meta
  • (default: false)
  • exclude Lightdash metadata from the generated .yml

Example:

Generate or update YAML file for a single dbt model to cover all columns in the database:

lightdash generate -s mymodel

lightdash generate-exposures

Generates a schema.yml file for Lightdash exposures.

danger

This command is still in beta and may be removed or updated without warning.

This command does not support using dbt options.

Options:

• --project-dir [path]
  • (default: ".")
  • The directory of the dbt project
• --output [path]
  • The path where the output exposures YAML file will be written

Example:

Create or update YAML file called lightdash-exposures.yml in the current directory with all exposures in Lightdash:

lightdash generate-exposures --output ./lightdash-exposures.yml

lightdash dbt run

Runs dbt and then generates or updates schema.yml file(s) for models that have columns missing or changed from the existing schema.yml files.

Any dbt option that works with dbt run will also work with lightdash dbt run. That includes all the Lightdash dbt options, and more (see dbt run docs).

Options:

• --exclude-meta
  • (default: false)
  • exclude Lightdash metadata from the generated .yml
• -y or --assume-yes
  • assume yes to prompts (default: false)

Examples:

Run a single model and create or update its schema.yml file:

lightdash dbt run --select mymodel

lightdash download

Downloads all charts and dashboards from your Lightdash project as code. A lightdash directory is created in your working directory and all of the charts and dashboards are written there as .yml files.

E.g. if you're running this command inside your dbt directory (eg: /home/javi/dbt) then it will create a folder (/home/javi/dbt/lightdash).

You can make changes to the code and upload these changes back to your Lightdash project. Content that's been downloaded as code can still be managed in the Lightdash UI.

Options:

• --charts or -c
  • select specific charts as code to download from your project. Use the chart SLUG, UUID or URL to specify the chart.
• --dashboards or -d
  • select specific dashboards as code to download from your project. Use the dashboard SLUG, UUID or URL to specify the dashboard.

Examples:

Download all charts and dashboards from your project.

lightdash download

Download a specific dashboard from your Lightdash project.

lightdash upload -d https://app.lightdash.cloud/my-dashboard-url

lightdash upload

Uploads charts and dashboards that you've made changes to from the lightdash/ directory in your dbt project to your Lightdash project. To upload new content as code to your project, you need to use the option --force (see Options below).

If there have been changes made to a chart or dashboard in the application that is being uploaded from code, lightdash upload will overwrite the changes.

Options:

• --force
  • if you've created new content as code that doesn't exist in your Lightdash project yet, you need to run lightdash upload --force to create these new charts and dashboards. Otherwise, lightdash upload only uploads updates to existing content.
• --charts or -c
  • select specific charts as code to upload back to your project. Use the chart SLUG to specify the chart.
• --dashboards or -d
  • select specific dashboards as code to upload back to your project. Use the dashboard SLUG to specify the dashboard.

Examples:

Upload all charts and dashboards in code from your lightdash/ directory to your Lightdash project.

lightdash upload

Upload a specific dashboard to your Lightdash project.

lightdash upload -d my-dashboard-slug

dbt options

These are options from the dbt Core CLI that also work with some Lightdash CLI commands.

dbt node selection

You can select a subset of your dbt models by using the following options on any Lightdash commands that support dbt options.

Node selection:

• --select [models...] or -s [models...]
  • Read the dbt docs on select
• --exclude [models...]
  • Read the dbt docs on exclude
• --selector [selector_name]
  • Read the dbt docs on selector

dbt flags

These dbt flags work with Lightdash commands that support dbt options. Read the dbt docs on global config flags for details.

• --project-dir [path]
• --profiles-dir [path]
• --profile [name]
• --target [name]
• --no-version-check
• --state [state]
• --full-refresh

dbt project variables

You can set dbt project variables in Lightdash commands that support dbt options. Read the dbt docs on project variables for details.

--vars [vars]

dbt threads

You can set the number of threads for dbt in Lightdash commands that support dbt options. Read the dbt docs on threads for details.

--threads [number]