Skip to content

Document the CLI's in-place preview credential refresh (+1 more) #1642

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
lightdash-bot wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Document the CLI's in-place preview credential refresh (+1 more) #1642

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
89f3e7c
Document the Tags field for dbt Cloud connections
lightdash-bot Nov 1, 2026
050f7c7
Document the CLI's in-place preview credential refresh
lightdash-bot Nov 1, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions integrations/connect-project.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1772,6 +1772,16 @@ The dbt Cloud metadata API host for your region. Must use `https://`. Match it t
- EU multi-tenant: `https://metadata.eu1.dbt.com`
- Cell-based (URL like `abc123.us1.dbt.com`): `https://<prefix>.metadata.us1.dbt.com`

##### Tags

Only models that carry **all** the tags you list here are synced. Lightdash passes the tags as a filter to the dbt Cloud Discovery API, together with `lastRunStatus: success`, so a model is synced only if it has every listed tag in the connected environment's last successful run. The [dbt selector](/integrations/dbt/projects#dbt-selector) setting doesn't apply to dbt Cloud connections.

Limiting the synced models also reduces the number of warehouse tables Lightdash looks up on each refresh.

<Warning>
If no model in the last successful run carries all the listed tags, the sync fails with "No models found". After you add a tag to a model in dbt, a job must run in that environment before you refresh Lightdash — Lightdash only sees tags from the environment's last successful run.
</Warning>

***

### CLI <a id="-cli" />
Expand Down
15 changes: 14 additions & 1 deletion workflow/preview-projects.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -106,6 +106,8 @@ It can also fail if your warehouse identity doesn't have permission to run queri

To use the upstream project's saved warehouse connection instead of your own credentials, run `lightdash preview --no-warehouse-credentials`.

If queries fail with a session-expired error (for example `Your Redshift IAM AWS session has expired`), see [Redshift with `method: iam`](#redshift-with-method-iam) to refresh the credentials on your existing preview instead of recreating it.

### Switch between previews

The CLI keeps one active preview: the last one you started. `lightdash deploy`, `lightdash upload`, and `lightdash download` ask whether to use it or your production project, and use the preview in non-interactive mode. Starting another preview doesn't delete the previous one. It stays on the server until you run `lightdash stop-preview --name` with its name, or it [expires](#preview-expiration).
Expand All @@ -127,7 +129,18 @@ aws sso login --profile my-redshift-profile
lightdash preview
```

Because SSO and role credentials are short-lived, the CLI prints a warning showing the expiry when it forwards temporary credentials. Queries in the preview project will stop working once the session expires. Re-run `aws sso login` and `lightdash preview` to refresh them.
Because SSO and role credentials are short-lived, the CLI prints a warning showing the expiry when it forwards temporary credentials. Queries in the preview project will stop working once the session expires.

On CLI 2.186.1 or newer, you don't need to stop and recreate the preview to refresh them. Update the CLI (`npm i -g @lightdash/cli@latest` — CLI versions compare numerically per segment, so 2.449 is newer than 2.57), sign in again, then re-run `start-preview` with the same `--name`:

```bash
aws sso login --profile my-redshift-profile
lightdash start-preview --name "my-preview"
```

This pushes the newly resolved credentials into the existing preview instead of creating a new one, so content you've built in the preview — dashboards, data apps — stays in place. The command prints `Warehouse credentials refreshed` on success. If it prints `Keeping the warehouse credentials already stored on the preview` instead, the refresh was skipped — most often because the prompt to let Lightdash store your warehouse credentials was declined. Pass `-y`/`--assume-yes` to accept that prompt automatically. The refresh is also skipped when the preview was started with `--no-warehouse-credentials` or an organization warehouse credential, since neither reads credentials from your local `profiles.yml`. The refreshed connection keeps any SSH tunnel settings inherited from the upstream project.

The same refresh applies to any other warehouse credentials the CLI resolves locally and that expire, such as a Snowflake SSO session.

<Note>
This applies to ephemeral preview projects created from your local dbt profile. For a durable, persistent project connection to Redshift with IAM, use a role the Lightdash backend assumes (`assumeRoleArn`). See [Connect Redshift](/integrations/connect-project#redshift).
Expand Down
Loading