From b62342560e429b9c216666acf42d28b07134493d Mon Sep 17 00:00:00 2001 From: Tori Whaley Date: Thu, 19 Feb 2026 11:55:51 -0500 Subject: [PATCH 1/3] Add safety warnings for lightdash deploy vs lightdash preview A customer accidentally overwrote their production semantic layer by running lightdash deploy from a local branch via an AI coding assistant. This adds prominent warnings to the CLI reference, deploy guide, and preview guide to prevent this from happening again. Co-Authored-By: Claude Opus 4.6 --- guides/cli/how-to-use-lightdash-deploy.mdx | 11 +++++++++-- guides/cli/how-to-use-lightdash-preview.mdx | 4 ++++ references/lightdash-cli.mdx | 10 ++++++++-- 3 files changed, 21 insertions(+), 4 deletions(-) diff --git a/guides/cli/how-to-use-lightdash-deploy.mdx b/guides/cli/how-to-use-lightdash-deploy.mdx index 1d827084..5fe6cea5 100644 --- a/guides/cli/how-to-use-lightdash-deploy.mdx +++ b/guides/cli/how-to-use-lightdash-deploy.mdx @@ -16,10 +16,17 @@ This guide will walk you through how it works, when to use each option, and what ## Before you deploy: A quick word of caution -Running `lightdash deploy` uses your local dbt profile (from your `profiles.yml`). If your local profile isn't pointing to production, you could deploy to the wrong environment. -This works in simple setups, but can introduce risk when using multiple environments or working in a team. +**`lightdash deploy` pushes directly to your production project.** + +Running this command uses your local dbt profile (from your `profiles.yml`). If your default target points to a dev or staging environment, `lightdash deploy` will overwrite your production semantic layer with that configuration — breaking dashboards for all users. + +This is the most common way teams accidentally break production. If you're working locally, **use [`lightdash preview`](/guides/cli/how-to-use-lightdash-preview) instead** — it creates a temporary, isolated project that won't affect production. + +**Using AI coding assistants?** Tools like Claude, Cursor, and other AI assistants may run CLI commands on your behalf. Make sure any AI tooling in your workflow uses `lightdash preview` (not `lightdash deploy`) for local development. You can enforce this by adding instructions to your project's `CLAUDE.md`, `.cursorrules`, or equivalent configuration file. + + For a safer, scalable approach to deploying and previewing changes, use CI/CD. This allows you to: * Spin up Lightdash preview environments for each PR diff --git a/guides/cli/how-to-use-lightdash-preview.mdx b/guides/cli/how-to-use-lightdash-preview.mdx index d3317148..0ab84cd0 100644 --- a/guides/cli/how-to-use-lightdash-preview.mdx +++ b/guides/cli/how-to-use-lightdash-preview.mdx @@ -6,6 +6,10 @@ icon: "vial" Preview projects will copy all spaces/charts/dashboards into your new preview project, so you can test the content and also run [validation](/guides/cli/how-to-use-lightdash-validate). This is only copied on preview creation, you can't sync the content afterwards. + +**Always use `lightdash preview` when developing locally.** Unlike `lightdash deploy`, which pushes directly to your production project, `lightdash preview` creates a temporary, isolated environment where you can safely test changes without affecting production dashboards. When you're ready to deploy to production, use [CI/CD](/guides/cli/automate-cli-workflow) or see the [deploy guide](/guides/cli/how-to-use-lightdash-deploy). + + ### Run `lightdash preview` from inside your project ```bash diff --git a/references/lightdash-cli.mdx b/references/lightdash-cli.mdx index ebae015e..d939f132 100644 --- a/references/lightdash-cli.mdx +++ b/references/lightdash-cli.mdx @@ -370,9 +370,15 @@ lightdash stop-preview "neon unicorn" Compiles and deploys the current project to your [selected Lightdash Cloud project](#lightdash-config-set-project). - **It is not common practice to use this command from the CLI after initial project creation.** + **`lightdash deploy` pushes directly to your production project. Use with caution.** - This command is usually [used in Github Actions](/guides/cli/how-to-use-lightdash-deploy#automatically-deploy-your-changes-to-lightdash-using-a-github-action) or other deploy scripts. + Running this command from a local branch will overwrite your production semantic layer with whatever is compiled locally — including any dev or staging targets from your `profiles.yml`. This can break dashboards for all users. + + **Use [`lightdash preview`](#lightdash-preview) for local development and testing.** Preview creates a temporary, isolated project that won't affect production. + + For production deploys, we recommend using [CI/CD with GitHub Actions](/guides/cli/how-to-use-lightdash-deploy#automatically-deploy-your-changes-to-lightdash-using-a-github-action) instead of running `lightdash deploy` from the CLI. + + This is especially important if you're using AI coding assistants (like Claude, Cursor, etc.) that may run CLI commands — make sure they use `lightdash preview`, not `lightdash deploy`. All standard [dbt options](#dbt-options) work with `lightdash deploy`. From e4015d697b9a78a961eceb04fe1c5970e8ad15be Mon Sep 17 00:00:00 2001 From: Tori Whaley Date: Thu, 19 Feb 2026 12:00:19 -0500 Subject: [PATCH 2/3] Remove AI assistant references, em dashes, and redundant tip Skills guardrails for deploy are being built in-product, so removing the AI-specific callouts from docs. Also removes em dashes and the redundant tip from the preview guide. Co-Authored-By: Claude Opus 4.6 --- guides/cli/how-to-use-lightdash-deploy.mdx | 10 +++------- guides/cli/how-to-use-lightdash-preview.mdx | 4 ---- references/lightdash-cli.mdx | 4 +--- 3 files changed, 4 insertions(+), 14 deletions(-) diff --git a/guides/cli/how-to-use-lightdash-deploy.mdx b/guides/cli/how-to-use-lightdash-deploy.mdx index 5fe6cea5..f86b4f23 100644 --- a/guides/cli/how-to-use-lightdash-deploy.mdx +++ b/guides/cli/how-to-use-lightdash-deploy.mdx @@ -18,15 +18,11 @@ This guide will walk you through how it works, when to use each option, and what **`lightdash deploy` pushes directly to your production project.** -Running this command uses your local dbt profile (from your `profiles.yml`). If your default target points to a dev or staging environment, `lightdash deploy` will overwrite your production semantic layer with that configuration — breaking dashboards for all users. +Running this command uses your local dbt profile (from your `profiles.yml`). If your default target points to a dev or staging environment, `lightdash deploy` will overwrite your production semantic layer with that configuration, breaking dashboards for all users. -This is the most common way teams accidentally break production. If you're working locally, **use [`lightdash preview`](/guides/cli/how-to-use-lightdash-preview) instead** — it creates a temporary, isolated project that won't affect production. +If you're working locally, **use [`lightdash preview`](/guides/cli/how-to-use-lightdash-preview) instead**. It creates a temporary, isolated project that won't affect production. - -**Using AI coding assistants?** Tools like Claude, Cursor, and other AI assistants may run CLI commands on your behalf. Make sure any AI tooling in your workflow uses `lightdash preview` (not `lightdash deploy`) for local development. You can enforce this by adding instructions to your project's `CLAUDE.md`, `.cursorrules`, or equivalent configuration file. - - For a safer, scalable approach to deploying and previewing changes, use CI/CD. This allows you to: * Spin up Lightdash preview environments for each PR @@ -60,7 +56,7 @@ If your dbt project uses different profiles or targets for dev and prod, you can lightdash deploy --profile prod ``` -Be careful — if your local prod profile isn't properly pointing to your production database, +Be careful. If your local prod profile isn't properly pointing to your production database, this can result in incorrect connections (e.g. accidentally deploying to a dev dataset). diff --git a/guides/cli/how-to-use-lightdash-preview.mdx b/guides/cli/how-to-use-lightdash-preview.mdx index 0ab84cd0..d3317148 100644 --- a/guides/cli/how-to-use-lightdash-preview.mdx +++ b/guides/cli/how-to-use-lightdash-preview.mdx @@ -6,10 +6,6 @@ icon: "vial" Preview projects will copy all spaces/charts/dashboards into your new preview project, so you can test the content and also run [validation](/guides/cli/how-to-use-lightdash-validate). This is only copied on preview creation, you can't sync the content afterwards. - -**Always use `lightdash preview` when developing locally.** Unlike `lightdash deploy`, which pushes directly to your production project, `lightdash preview` creates a temporary, isolated environment where you can safely test changes without affecting production dashboards. When you're ready to deploy to production, use [CI/CD](/guides/cli/automate-cli-workflow) or see the [deploy guide](/guides/cli/how-to-use-lightdash-deploy). - - ### Run `lightdash preview` from inside your project ```bash diff --git a/references/lightdash-cli.mdx b/references/lightdash-cli.mdx index d939f132..2ae2e523 100644 --- a/references/lightdash-cli.mdx +++ b/references/lightdash-cli.mdx @@ -372,13 +372,11 @@ Compiles and deploys the current project to your [selected Lightdash Cloud proje **`lightdash deploy` pushes directly to your production project. Use with caution.** - Running this command from a local branch will overwrite your production semantic layer with whatever is compiled locally — including any dev or staging targets from your `profiles.yml`. This can break dashboards for all users. + Running this command from a local branch will overwrite your production semantic layer with whatever is compiled locally, including any dev or staging targets from your `profiles.yml`. This can break dashboards for all users. **Use [`lightdash preview`](#lightdash-preview) for local development and testing.** Preview creates a temporary, isolated project that won't affect production. For production deploys, we recommend using [CI/CD with GitHub Actions](/guides/cli/how-to-use-lightdash-deploy#automatically-deploy-your-changes-to-lightdash-using-a-github-action) instead of running `lightdash deploy` from the CLI. - - This is especially important if you're using AI coding assistants (like Claude, Cursor, etc.) that may run CLI commands — make sure they use `lightdash preview`, not `lightdash deploy`. All standard [dbt options](#dbt-options) work with `lightdash deploy`. From c5dbc0faf49eb3b63669af32c47a6dc2366babbe Mon Sep 17 00:00:00 2001 From: Tori Whaley Date: Thu, 19 Feb 2026 12:06:26 -0500 Subject: [PATCH 3/3] Trim redundant phrasing from deploy warning Co-Authored-By: Claude Opus 4.6 --- references/lightdash-cli.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/references/lightdash-cli.mdx b/references/lightdash-cli.mdx index 2ae2e523..3c5d3175 100644 --- a/references/lightdash-cli.mdx +++ b/references/lightdash-cli.mdx @@ -370,13 +370,13 @@ lightdash stop-preview "neon unicorn" Compiles and deploys the current project to your [selected Lightdash Cloud project](#lightdash-config-set-project). - **`lightdash deploy` pushes directly to your production project. Use with caution.** + **`lightdash deploy` pushes directly to your production project.** Running this command from a local branch will overwrite your production semantic layer with whatever is compiled locally, including any dev or staging targets from your `profiles.yml`. This can break dashboards for all users. **Use [`lightdash preview`](#lightdash-preview) for local development and testing.** Preview creates a temporary, isolated project that won't affect production. - For production deploys, we recommend using [CI/CD with GitHub Actions](/guides/cli/how-to-use-lightdash-deploy#automatically-deploy-your-changes-to-lightdash-using-a-github-action) instead of running `lightdash deploy` from the CLI. + For production deploys, we recommend using [CI/CD with GitHub Actions](/guides/cli/how-to-use-lightdash-deploy#automatically-deploy-your-changes-to-lightdash-using-a-github-action). All standard [dbt options](#dbt-options) work with `lightdash deploy`.