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.
The Lightdash CLI requires Node, NPM, and the dbt core or dbt cloud CLI to be installed and available under the dbt
command.
Warehouse credentials dependency for some commands
Affected commands: lightdash generate
, lightdash preview
and lightdash start-preview
These commands rely on the warehouse credentials from the active project, as the dbt Cloud CLI does not expose credentials directly. Ensure the project’s credentials have access to all development and staging schemas for a seamless experience.
Empty warehouse credentials for new projects
Affected commands: lightdash deploy --create
When using this command to create a new project that is not a preview, the warehouse credentials will not be populated automatically. Users must update the warehouse credentials manually in the project settings page after the project is created.
There are three global options that can be used with any Lightdash CLI command: version, help, and verbose.
--version
or -V
Ignores the preceding command and shows the installed CLI version. Usually it’s used right after lightdash
, like this:
If you need to upgrade your version of the Lightdash cli, run the following in your terminal:
--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:
That returns the Lightdash CLI help menu:
When you use the --help
or -h
option with a speific command:
That returns details and examples for the command itself:
--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
:
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 |
---|---|
lightdash login | Log in to a Lightdash instance using email/password or a token |
lightdash config set-project | Choose or set the Lightdash project you are working on |
lightdash compile | Compile lightdash resources using your local project files |
lightdash preview | Create a temporary preview project, then wait for a keypress to stop |
lightdash start-preview | Create a preview project that stays open until it is stopped |
lightdash stop-preview | Shut down an open preview project |
lightdash deploy | Compile and deploy a Lightdash project using your local project and credentials |
lightdash refresh | Refresh Lightdash project with remote repository |
lightdash validate | Validate content from your active project against your local project files |
lightdash generate | Generate or update schema.yml file(s) for the selected model(s) |
lightdash dbt run | Run dbt, then generate or update schema.yml file(s) for the selected model(s) |
lightdash generate-exposures | [Experimental command] Generates a YAML file for Lightdash exposures |
lightdash download | Download all charts and dashboards from your Lightdash project as code |
lightdash upload | Upload charts and dashboards as code to your Lightdash project |
lightdash rename | Rename model or field names across all your Lightdash content |
lightdash login
Log in to a Lightdash instance using email and password or a token.
Argument:
[URL]
Options:
--token
Examples:
Log in to Lightdash Cloud US instance (for most Starter customers):
Log in to Lightdash Cloud EU instance while showing detailed logs of login process:
Log in to a custom domain with a personal access token (exclude --token
to log in with email and password):
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!
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
--uuid
Examples:
Set project to “Healthcare Demo”:
Set project to the one with this UUID:
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:
Compile only the accounts
dbt model, then your Lightdash explores:
Compile your project using the production
profile from your local profiles.yml
file:
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]
--start-of-week [number]
--skip-dbt-compile
dbt compile
and deploy from the existing ./target/manifest.json--skip-warehouse-catalog
--use-dbt-list [true/false]
dbt list
instead of dbt compile
to generate dbt manifest.json--ignore-errors
Examples:
Create a temporary preview project with the name PR: Add Revenue Metric and ignore validation errors while spinning it up:
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 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]
Options:
--start-of-week [number]
--skip-dbt-compile
dbt compile
and deploy from the existing ./target/manifest.json--skip-warehouse-catalog
--use-dbt-list [true/false]
dbt list
instead of dbt compile
to generate dbt manifest.json--ignore-errors
lightdash stop-preview
Shuts down a project that was created with .
This command does not support using dbt options.
Required argument:
--name [preview name]
Example:
Shut down the preview project named neon unicorn.
lightdash deploy
Compiles and deploys the current project to your selected Lightdash Cloud project.
It is not common practice to use this command from the CLI after initial project creation.
This command is usually used in Github Actions or other deploy scripts.
All standard dbt options work with lightdash deploy
.
Options:
--create [project_name]
--ignore-errors
--start-of-week [number]
--skip-dbt-compile
dbt compile
and deploy from the existing ./target/manifest.json.--skip-warehouse-catalog
--use-dbt-list [true|false]
dbt list
instead of dbt compile
to generate dbt manifest.json.Example:
Create a new project that uses the production
credentials from your local dbt profiles.yml
:
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]
--preview
--skip-dbt-compile
dbt compile
and deploy from the existing ./target/manifest.json.--skip-warehouse-catalog
--use-dbt-list [true/false]
dbt list
instead of dbt compile
to generate dbt manifest.json.--only [elems...]
Example:
Validate only dashboards and use the existing compiled dbt manifest:
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
--exclude-meta
--preserve-column-case
Example:
Generate or update YAML file for a single dbt model to cover all columns in the database:
lightdash generate-exposures
Generates a schema.yml
file for Lightdash exposures.
This command is still in beta and may be removed or updated without warning.
Only Project Admins can execute this command, since it requires access to all spaces (including private ones).
This command does not support using dbt options.
Options:
--project-dir [path]
--output [path]
Example:
Create or update YAML file called lightdash-exposures.yml
in the current directory with all exposures in Lightdash:
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
-y
or --assume-yes
-no
or --assume-no
--preserve-column-case
Example:
Run a single model and create or update its schema.yml
file:
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
--dashboards
or -d
--path
or -p
--project <project uuid>
123-project-uuid
https://app.lightdash.cloud/projects/123-project-uuid/
Examples:
Download all charts and dashboards from your project.
Download a specific dashboard from your Lightdash project.
Download all content from a project to the directory /Users/katiehindson/lightdash/lightdash-analytics/
This will create: /Users/katiehindson/lightdash/lightdash-analytics/charts/
and /Users/katiehindson/lightdash/lightdash-analytics/dashboards
and save the content to these new folders.
You can also use relative paths like:
Download all charts and dashboards from a specific project.
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
lightdash upload --force
to create these new charts and dashboards. Otherwise, lightdash upload
only uploads updates to existing content.--charts
or -c
--dashboards
or -d
--path
or -p
--project <project uuid>
123-project-uuid
https://app.lightdash.cloud/projects/123-project-uuid/
Examples:
Upload all charts and dashboards in code from your lightdash/
directory to your Lightdash project.
Upload a specific dashboard to your Lightdash project.
Upload content from the directory /Users/katiehindson/lightdash/lightdash-analytics/
This will upload all content from: /Users/katiehindson/lightdash/lightdash-analytics/charts/
and /Users/katiehindson/lightdash/lightdash-analytics/dashboards
and save the content to these new folders.
You can also use relative paths like:
Upload all charts and dashboards from your lightdash/
directory to a specific project.
lightdash rename
Rename model or field names across all content in your Lightdash project. This command will do a full find and replace on a field or table so all references in chart fields, dashboard filters, table calculations, custom metrics, etc. can be changed at once.
Arguments:
--type
field
or model
--from
num_users
)--to
count_distinct_user_id
)Options:
--project
, -p
lightdash config set-project
)--model
, -m
--dry-run
--list
--assume-yes
, -y
Examples:
Rename the field num_users
to count_distinct_user_id
.
Do a dry run of changing the table reference from users_mart_v1
to users
.
Rename the field count
to count_distinct_order_id
in the orders
model and list all affected content when complete:
These are options from the dbt Core CLI that also work with some Lightdash CLI commands.
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...]
--exclude [models...]
--selector [selector_name]
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
--defer
(works with lightdash preview
and lightdash compile
)You can set dbt project variables in Lightdash commands that support dbt options. Read the dbt docs on project variables for details.
--vars [vars]
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]
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.
The Lightdash CLI requires Node, NPM, and the dbt core or dbt cloud CLI to be installed and available under the dbt
command.
Warehouse credentials dependency for some commands
Affected commands: lightdash generate
, lightdash preview
and lightdash start-preview
These commands rely on the warehouse credentials from the active project, as the dbt Cloud CLI does not expose credentials directly. Ensure the project’s credentials have access to all development and staging schemas for a seamless experience.
Empty warehouse credentials for new projects
Affected commands: lightdash deploy --create
When using this command to create a new project that is not a preview, the warehouse credentials will not be populated automatically. Users must update the warehouse credentials manually in the project settings page after the project is created.
There are three global options that can be used with any Lightdash CLI command: version, help, and verbose.
--version
or -V
Ignores the preceding command and shows the installed CLI version. Usually it’s used right after lightdash
, like this:
If you need to upgrade your version of the Lightdash cli, run the following in your terminal:
--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:
That returns the Lightdash CLI help menu:
When you use the --help
or -h
option with a speific command:
That returns details and examples for the command itself:
--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
:
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 |
---|---|
lightdash login | Log in to a Lightdash instance using email/password or a token |
lightdash config set-project | Choose or set the Lightdash project you are working on |
lightdash compile | Compile lightdash resources using your local project files |
lightdash preview | Create a temporary preview project, then wait for a keypress to stop |
lightdash start-preview | Create a preview project that stays open until it is stopped |
lightdash stop-preview | Shut down an open preview project |
lightdash deploy | Compile and deploy a Lightdash project using your local project and credentials |
lightdash refresh | Refresh Lightdash project with remote repository |
lightdash validate | Validate content from your active project against your local project files |
lightdash generate | Generate or update schema.yml file(s) for the selected model(s) |
lightdash dbt run | Run dbt, then generate or update schema.yml file(s) for the selected model(s) |
lightdash generate-exposures | [Experimental command] Generates a YAML file for Lightdash exposures |
lightdash download | Download all charts and dashboards from your Lightdash project as code |
lightdash upload | Upload charts and dashboards as code to your Lightdash project |
lightdash rename | Rename model or field names across all your Lightdash content |
lightdash login
Log in to a Lightdash instance using email and password or a token.
Argument:
[URL]
Options:
--token
Examples:
Log in to Lightdash Cloud US instance (for most Starter customers):
Log in to Lightdash Cloud EU instance while showing detailed logs of login process:
Log in to a custom domain with a personal access token (exclude --token
to log in with email and password):
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!
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
--uuid
Examples:
Set project to “Healthcare Demo”:
Set project to the one with this UUID:
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:
Compile only the accounts
dbt model, then your Lightdash explores:
Compile your project using the production
profile from your local profiles.yml
file:
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]
--start-of-week [number]
--skip-dbt-compile
dbt compile
and deploy from the existing ./target/manifest.json--skip-warehouse-catalog
--use-dbt-list [true/false]
dbt list
instead of dbt compile
to generate dbt manifest.json--ignore-errors
Examples:
Create a temporary preview project with the name PR: Add Revenue Metric and ignore validation errors while spinning it up:
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 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]
Options:
--start-of-week [number]
--skip-dbt-compile
dbt compile
and deploy from the existing ./target/manifest.json--skip-warehouse-catalog
--use-dbt-list [true/false]
dbt list
instead of dbt compile
to generate dbt manifest.json--ignore-errors
lightdash stop-preview
Shuts down a project that was created with .
This command does not support using dbt options.
Required argument:
--name [preview name]
Example:
Shut down the preview project named neon unicorn.
lightdash deploy
Compiles and deploys the current project to your selected Lightdash Cloud project.
It is not common practice to use this command from the CLI after initial project creation.
This command is usually used in Github Actions or other deploy scripts.
All standard dbt options work with lightdash deploy
.
Options:
--create [project_name]
--ignore-errors
--start-of-week [number]
--skip-dbt-compile
dbt compile
and deploy from the existing ./target/manifest.json.--skip-warehouse-catalog
--use-dbt-list [true|false]
dbt list
instead of dbt compile
to generate dbt manifest.json.Example:
Create a new project that uses the production
credentials from your local dbt profiles.yml
:
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]
--preview
--skip-dbt-compile
dbt compile
and deploy from the existing ./target/manifest.json.--skip-warehouse-catalog
--use-dbt-list [true/false]
dbt list
instead of dbt compile
to generate dbt manifest.json.--only [elems...]
Example:
Validate only dashboards and use the existing compiled dbt manifest:
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
--exclude-meta
--preserve-column-case
Example:
Generate or update YAML file for a single dbt model to cover all columns in the database:
lightdash generate-exposures
Generates a schema.yml
file for Lightdash exposures.
This command is still in beta and may be removed or updated without warning.
Only Project Admins can execute this command, since it requires access to all spaces (including private ones).
This command does not support using dbt options.
Options:
--project-dir [path]
--output [path]
Example:
Create or update YAML file called lightdash-exposures.yml
in the current directory with all exposures in Lightdash:
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
-y
or --assume-yes
-no
or --assume-no
--preserve-column-case
Example:
Run a single model and create or update its schema.yml
file:
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
--dashboards
or -d
--path
or -p
--project <project uuid>
123-project-uuid
https://app.lightdash.cloud/projects/123-project-uuid/
Examples:
Download all charts and dashboards from your project.
Download a specific dashboard from your Lightdash project.
Download all content from a project to the directory /Users/katiehindson/lightdash/lightdash-analytics/
This will create: /Users/katiehindson/lightdash/lightdash-analytics/charts/
and /Users/katiehindson/lightdash/lightdash-analytics/dashboards
and save the content to these new folders.
You can also use relative paths like:
Download all charts and dashboards from a specific project.
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
lightdash upload --force
to create these new charts and dashboards. Otherwise, lightdash upload
only uploads updates to existing content.--charts
or -c
--dashboards
or -d
--path
or -p
--project <project uuid>
123-project-uuid
https://app.lightdash.cloud/projects/123-project-uuid/
Examples:
Upload all charts and dashboards in code from your lightdash/
directory to your Lightdash project.
Upload a specific dashboard to your Lightdash project.
Upload content from the directory /Users/katiehindson/lightdash/lightdash-analytics/
This will upload all content from: /Users/katiehindson/lightdash/lightdash-analytics/charts/
and /Users/katiehindson/lightdash/lightdash-analytics/dashboards
and save the content to these new folders.
You can also use relative paths like:
Upload all charts and dashboards from your lightdash/
directory to a specific project.
lightdash rename
Rename model or field names across all content in your Lightdash project. This command will do a full find and replace on a field or table so all references in chart fields, dashboard filters, table calculations, custom metrics, etc. can be changed at once.
Arguments:
--type
field
or model
--from
num_users
)--to
count_distinct_user_id
)Options:
--project
, -p
lightdash config set-project
)--model
, -m
--dry-run
--list
--assume-yes
, -y
Examples:
Rename the field num_users
to count_distinct_user_id
.
Do a dry run of changing the table reference from users_mart_v1
to users
.
Rename the field count
to count_distinct_order_id
in the orders
model and list all affected content when complete:
These are options from the dbt Core CLI that also work with some Lightdash CLI commands.
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...]
--exclude [models...]
--selector [selector_name]
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
--defer
(works with lightdash preview
and lightdash compile
)You can set dbt project variables in Lightdash commands that support dbt options. Read the dbt docs on project variables for details.
--vars [vars]
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]