From 894011731c3f3db69adf60f69980ece03d5b8f34 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Thu, 16 Jul 2026 00:43:26 +0000 Subject: [PATCH 1/2] docs: document Snowflake CLI SSO login and warehouse-first onboarding --- .../setup-lightdash/connect-project.mdx | 53 ++++++++++++++++++- references/lightdash-cli.mdx | 49 +++++++++++++++++ 2 files changed, 101 insertions(+), 1 deletion(-) diff --git a/get-started/setup-lightdash/connect-project.mdx b/get-started/setup-lightdash/connect-project.mdx index 5f6723b0..3402c685 100644 --- a/get-started/setup-lightdash/connect-project.mdx +++ b/get-started/setup-lightdash/connect-project.mdx @@ -55,6 +55,14 @@ We currently support: We always recommend giving read-only permissions to Lightdash, that way you ensure than no data can be manipulated. See each section below for warehouse specific details. + + When the `warehouse-connect-onboarding` feature flag is enabled, the **Create new project** screen shows a **Connect to your warehouse** option alongside the standard "Connect via CLI" and "Connect manually" flows. + + Choosing it takes you directly to the warehouse connection form and creates the project with dbt type `NONE` — no dbt project is imported and no dbt compilation runs. Explores are populated directly from the warehouse catalog instead of dbt models, so this is a good fit if you want to start exploring your data before you have a dbt project set up. You can add or switch to a dbt project later from **Project settings**. + + Combine this with **Connect via Lightdash CLI (SSO)** on Snowflake (see below) to create a project without ever pasting a credential. + + Since we host your Lightdash for you, you may need to add our static IP addresses to the allow-list for your security group or firewall rules so they don’t block calls from your Lightdash Cloud to your connected databases. @@ -668,7 +676,50 @@ If you're a snowflake admin you can list all users available in the snowflake co ##### Authentication type -Choose to authenticate using either a user account (using "Sign in with Snowflake") or with a service account using a JSON key file or password. +Choose to authenticate using either a user account (using "Sign in with Snowflake" or "Connect via Lightdash CLI (SSO)") or with a service account using a JSON key file or password. + +##### Connect via Lightdash CLI (SSO) + + + This method is available behind the `warehouse-connect-onboarding` feature flag and only applies during **project creation**. Contact Lightdash support to enable it for your workspace. + + +Use this when your Snowflake account requires SSO (or MFA) and you don't want to paste a password, private key, or PAT to create the project. The Lightdash CLI signs you in to Snowflake in your browser and provisions a durable credential that is deposited straight into the project connection form — you never handle the secret yourself. + +**How it works:** + +1. In the Snowflake connection form, choose **Connect via Lightdash CLI (SSO)**. Lightdash generates a single-use connect code (valid for 15 minutes) and shows the CLI command to run. +2. Run the command shown in the setup wizard from a machine that has the [Lightdash CLI](/references/lightdash-cli) installed: + + ```bash + lightdash connect-snowflake \ + --url https://app.lightdash.cloud \ + --code \ + --account ecomstore-xy12345 + ``` + +3. The CLI opens your Snowflake SSO login in a browser. Once you sign in, the CLI mints a durable Snowflake credential and deposits it into the setup wizard tab. +4. The wizard shows **Connected as `` ✓**. Pick a database, warehouse, role, and schema from the session-populated dropdowns (or accept the session defaults), then submit the form to create the project. + +**Credential type the CLI provisions:** + +The CLI never deposits your raw SSO token. It tries, in order: + +1. **Key-pair authentication (preferred)** — generates a local RSA-2048 key-pair and registers the public key in the first free slot on your Snowflake user with `ALTER USER … SET RSA_PUBLIC_KEY`. The key is verified with a diagnostic connection before deposit. +2. **Programmatic Access Token (PAT)** — if key-pair provisioning fails (for example, because both `RSA_PUBLIC_KEY` slots are already in use), the CLI falls back to a Snowflake [Programmatic Access Token](https://docs.snowflake.com/en/user-guide/programmatic-access-tokens) valid for 365 days. + +If both fail, the CLI prints admin remediation SQL and exits without depositing a credential. + +**Optional flags:** + +You can preset any of `--user`, `--database`, `--warehouse`, `--role`, or `--schema`. Anything not provided is filled from your Snowflake session defaults, or picked in the browser tab from the discovered options. + +**Security notes:** + +- The connect code is single-use and expires after 15 minutes; only a SHA-256 hash of it is stored server-side. +- Generating a new connect code invalidates any previous codes for your user. +- A code can only be claimed once, by the user who created it. +- Deposited credentials are encrypted at rest and cleared from the deposit store as soon as the browser tab claims them. ##### Sign in with Snowflake diff --git a/references/lightdash-cli.mdx b/references/lightdash-cli.mdx index 061d1271..932dc187 100644 --- a/references/lightdash-cli.mdx +++ b/references/lightdash-cli.mdx @@ -115,6 +115,7 @@ For examples and command-specific options, click through the command in the tabl | Command | Description | | --------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | |[`lightdash login`](/references/lightdash-cli#lightdash-login) | Log in to a Lightdash instance using email/password or a token | +|[`lightdash connect-snowflake`](/references/lightdash-cli#lightdash-connect-snowflake) | Sign in to Snowflake via SSO and deposit a durable credential into the setup wizard | |[`lightdash config set-project`](/references/lightdash-cli#lightdash-config-set-project) | Choose or set the Lightdash project you are working on | |[`lightdash config get-project`](/references/lightdash-cli#lightdash-config-get-project) | Get the current active project | |[`lightdash config list-projects`](/references/lightdash-cli#lightdash-config-list-projects) | List all non-preview projects in your organization | @@ -179,6 +180,54 @@ Log in to a custom domain with a personal access token (exclude `--token` to log lightdash login https://custom.lightdash.domain --token bv6105f53cb127087189cfib180a3131 ``` +### `lightdash connect-snowflake` + +Sign in to Snowflake using browser-based SSO and deposit a durable credential into an open Lightdash project setup wizard. Use this during project creation when your Snowflake account requires SSO or MFA and you want to avoid pasting a password, private key, or PAT. + + + This command is only useful during project creation and requires the `warehouse-connect-onboarding` feature flag to be enabled on your Lightdash instance. Start the flow from the **Connect via Lightdash CLI (SSO)** option on the Snowflake connection form — the wizard generates the one-time `--code` and shows the full command for you to run. + + +The CLI opens Snowflake SSO in a browser, then provisions a durable credential in this order: + +1. A locally-generated **RSA-2048 key-pair**, registered on your Snowflake user with `ALTER USER … SET RSA_PUBLIC_KEY` in the first free slot and verified with a diagnostic connection. +2. If key-pair provisioning fails, a **365-day Programmatic Access Token** (PAT). +3. If both fail, the CLI prints admin remediation SQL and exits without depositing a credential. + +The resulting credential is deposited into the browser tab that generated the code and used to create the project. Raw short-lived OAuth tokens are never deposited. + +```console +lightdash connect-snowflake --url --code --account +``` + +**Required options:** + +- `--url ` + - The URL of your Lightdash instance (for example `https://app.lightdash.cloud`). +- `--code ` + - The single-use connect code shown in the Snowflake connection form. Valid for 15 minutes. +- `--account ` + - Your Snowflake [account identifier](https://docs.snowflake.com/en/user-guide/admin-account-identifier) (for example `ecomstore-xy12345`). + +**Optional overrides:** + +Any of these that you omit are resolved from your Snowflake session defaults or picked in the browser tab after the credential is deposited. + +- `--user ` — Snowflake username override. +- `--database ` — default database. +- `--warehouse ` — default compute warehouse. +- `--role ` — Snowflake role to use. +- `--schema ` — default schema. + +**Example:** + +```bash +lightdash connect-snowflake \ + --url https://app.lightdash.cloud \ + --code 8f3c9a2b1e4d \ + --account ecomstore-xy12345 +``` + ### `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! From 8c5d2fbd36fd82e5e69d76a37502910870846244 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Sat, 18 Jul 2026 00:42:44 +0000 Subject: [PATCH 2/2] docs: rename feature flag and document warehouse SSO smart defaults --- get-started/setup-lightdash/connect-project.mdx | 12 ++++++++---- references/lightdash-cli.mdx | 2 +- 2 files changed, 9 insertions(+), 5 deletions(-) diff --git a/get-started/setup-lightdash/connect-project.mdx b/get-started/setup-lightdash/connect-project.mdx index 3402c685..c0a04d53 100644 --- a/get-started/setup-lightdash/connect-project.mdx +++ b/get-started/setup-lightdash/connect-project.mdx @@ -56,11 +56,11 @@ We currently support: We always recommend giving read-only permissions to Lightdash, that way you ensure than no data can be manipulated. See each section below for warehouse specific details. - When the `warehouse-connect-onboarding` feature flag is enabled, the **Create new project** screen shows a **Connect to your warehouse** option alongside the standard "Connect via CLI" and "Connect manually" flows. + When the `new-onboarding` feature flag is enabled, the **Create new project** screen shows a **Connect to your warehouse** option alongside the standard "Connect via CLI" and "Connect manually" flows. Choosing it takes you directly to the warehouse connection form and creates the project with dbt type `NONE` — no dbt project is imported and no dbt compilation runs. Explores are populated directly from the warehouse catalog instead of dbt models, so this is a good fit if you want to start exploring your data before you have a dbt project set up. You can add or switch to a dbt project later from **Project settings**. - Combine this with **Connect via Lightdash CLI (SSO)** on Snowflake (see below) to create a project without ever pasting a credential. + Combine this with **Connect via Lightdash CLI (SSO)** on Snowflake or **Sign in with Google** on BigQuery (see below) to create a project without ever pasting a credential — the same feature flag also enables smart defaults (recommended project, largest dataset/database, recommended warehouse) after you authenticate. @@ -117,6 +117,10 @@ You can choose to connect to BigQuery with a user account (using "Sign in with G When you use "Sign in with Google" - Lightdash will execute queries against bigquery with your personal google user account. This is the simplest way to get connected quickly using your existing account. + + When the `new-onboarding` feature flag is enabled, new BigQuery projects default to **Sign in with Google** and the setup wizard suggests smart defaults after you authenticate: a recommended **Project ID** based on your Google account's BigQuery activity, and the largest available **Dataset** (marked with a *Recommended · largest* badge in the picker). You can override either at any time. + + ##### Service account (JSON Key File) To have Lightdash connect to BigQuery with a service account, you need to create the account and JSON key. You can read more about [creating and managing service accounts with Google BigQuery in their docs](https://cloud.google.com/iam/docs/creating-managing-service-accounts). You will need permissions to create service accounts and keys in your Google Project. If you don't have the permissions, use your user account instead. @@ -681,7 +685,7 @@ Choose to authenticate using either a user account (using "Sign in with Snowflak ##### Connect via Lightdash CLI (SSO) - This method is available behind the `warehouse-connect-onboarding` feature flag and only applies during **project creation**. Contact Lightdash support to enable it for your workspace. + This method is available behind the `new-onboarding` feature flag and only applies during **project creation**. Contact Lightdash support to enable it for your workspace. Use this when your Snowflake account requires SSO (or MFA) and you don't want to paste a password, private key, or PAT to create the project. The Lightdash CLI signs you in to Snowflake in your browser and provisions a durable credential that is deposited straight into the project connection form — you never handle the secret yourself. @@ -699,7 +703,7 @@ Use this when your Snowflake account requires SSO (or MFA) and you don't want to ``` 3. The CLI opens your Snowflake SSO login in a browser. Once you sign in, the CLI mints a durable Snowflake credential and deposits it into the setup wizard tab. -4. The wizard shows **Connected as `` ✓**. Pick a database, warehouse, role, and schema from the session-populated dropdowns (or accept the session defaults), then submit the form to create the project. +4. The wizard shows **Connected as `` ✓** and pre-fills smart defaults from your Snowflake session inventory: the largest database is picked as the default, the recommended compute warehouse is auto-selected, and the first available schema in the chosen database is filled in. Adjust any of these from the dropdowns, then submit the form to create the project. **Credential type the CLI provisions:** diff --git a/references/lightdash-cli.mdx b/references/lightdash-cli.mdx index 932dc187..8e992933 100644 --- a/references/lightdash-cli.mdx +++ b/references/lightdash-cli.mdx @@ -185,7 +185,7 @@ lightdash login https://custom.lightdash.domain --token bv6105f53cb127087189cfib Sign in to Snowflake using browser-based SSO and deposit a durable credential into an open Lightdash project setup wizard. Use this during project creation when your Snowflake account requires SSO or MFA and you want to avoid pasting a password, private key, or PAT. - This command is only useful during project creation and requires the `warehouse-connect-onboarding` feature flag to be enabled on your Lightdash instance. Start the flow from the **Connect via Lightdash CLI (SSO)** option on the Snowflake connection form — the wizard generates the one-time `--code` and shows the full command for you to run. + This command is only useful during project creation and requires the `new-onboarding` feature flag to be enabled on your Lightdash instance. Start the flow from the **Connect via Lightdash CLI (SSO)** option on the Snowflake connection form — the wizard generates the one-time `--code` and shows the full command for you to run. The CLI opens Snowflake SSO in a browser, then provisions a durable credential in this order: