diff --git a/references/integrations/dbt-projects.mdx b/references/integrations/dbt-projects.mdx index 5f10f985..e49a60e8 100644 --- a/references/integrations/dbt-projects.mdx +++ b/references/integrations/dbt-projects.mdx @@ -121,22 +121,6 @@ For ready-to-use workflow templates, see the [`lightdash/cli-actions`](https://g -### `lightdash deploy` vs `lightdash refresh` - -The two CLI commands above (`lightdash deploy` and `lightdash refresh`) are often confused. Here's the quick difference: - -| | `lightdash deploy` | `lightdash refresh` | -| --- | --- | --- | -| **What it does** | Pushes your local dbt project to a Lightdash project. Runs `dbt compile` (or `dbt list`) locally to produce a fresh `manifest.json`, then sends the compiled models/explores to the Lightdash server. | Tells the Lightdash server to re-pull from the connected git remote and recompile, server-side. No local dbt run, no local files involved — it's the API-driven equivalent of clicking **Refresh dbt** in the UI. | -| **Where compilation happens** | Locally (laptop or CI runner) | Lightdash servers | -| **Requires a remote git connection?** | No | Yes | -| **Flags** | Many (`--project`, `--select`, `--full-refresh`, `--create`, `--use-batched-deploy`, etc.) | Essentially none (just `--verbose`) | -| **Use when** | You've changed dbt models or Lightdash YAML metadata locally and want those changes to land in a Lightdash project. | Lightdash already points at a git repo and you just want it to pull the latest. | - -**Rule of thumb:** -- Local dbt code you want to push → `deploy` -- Lightdash already points at a git repo and you just want it to pull the latest → `refresh` - ### Decision matrix | | #1 `lightdash deploy` — local CLI | #2 `lightdash deploy` — CI | #3 "Refresh dbt" — UI button | #4 `lightdash refresh` — CI | #5 `POST /refresh` API — CI | @@ -167,6 +151,8 @@ The two CLI commands above (`lightdash deploy` and `lightdash refresh`) are ofte - Local `lightdash deploy` (#1) for first-time setup, then graduate to one of the automated patterns above as soon as the project is stable. +Not sure whether to use `lightdash deploy` or `lightdash refresh`? Read about the [differences between the two commands](/references/lightdash-cli#lightdash-deploy-vs-lightdash-refresh) in the CLI reference. + ### Things to know diff --git a/references/lightdash-cli.mdx b/references/lightdash-cli.mdx index 4d03205c..2210f5cd 100644 --- a/references/lightdash-cli.mdx +++ b/references/lightdash-cli.mdx @@ -483,6 +483,21 @@ Refreshes your hosted Lightdash project using the latest code from your linked G This command does not support using dbt options. +### `lightdash deploy` vs `lightdash refresh` + +The two CLI commands above (`lightdash deploy` and `lightdash refresh`) are often confused. Here's the quick difference: + +| | `lightdash deploy` | `lightdash refresh` | +| --- | --- | --- | +| **What it does** | Pushes your local dbt project to a Lightdash project. Runs `dbt compile` (or `dbt list`) locally to produce a fresh `manifest.json`, then sends the compiled models/explores to the Lightdash server. | Tells the Lightdash server to re-pull from the connected git remote and recompile, server-side. No local dbt run, no local files involved — it's the API-driven equivalent of clicking **Refresh dbt** in the UI. | +| **Where compilation happens** | Locally (laptop or CI runner) | Lightdash servers | +| **Requires a remote git connection?** | No | Yes | +| **Flags** | Many (`--project`, `--select`, `--full-refresh`, `--create`, `--use-batched-deploy`, etc.) | Essentially none (just `--verbose`) | +| **Use when** | You've changed dbt models or Lightdash YAML metadata locally and want those changes to land in a Lightdash project. | Lightdash already points at a git repo and you just want it to pull the latest. | + +**Rule of thumb:** +- Local dbt code you want to push → `deploy` +- Lightdash already points at a git repo and you just want it to pull the latest → `refresh` ### `lightdash validate`