diff --git a/guides/cli/cli-authentication.mdx b/guides/cli/cli-authentication.mdx index 9d6a2be7..a1aea969 100644 --- a/guides/cli/cli-authentication.mdx +++ b/guides/cli/cli-authentication.mdx @@ -6,56 +6,91 @@ icon: "key" ## Login - - -To log in to your Lightdash instance using OAuth2, run the following command: +The CLI uses browser-based OAuth login by default, making authentication quick and easy. - ```bash - lightdash login https://{{ lightdash_domain }} --oauth - ``` +### Basic login - where `{{ lightdash_domain }}` is the address for your running Lightdash instance. For example Lightdash cloud users in the US would type `lightdash login https://app.lightdash.cloud` if you're in Europe you'd type`lightdash login https://eu1.lightdash.cloud`. -This will open a new tab in your default browser. Log in to your Lightdash account (if you're not already logged in), then authorize the lightdash-cli client. -Once authorized, you’ll be logged in and ready to use the CLI. +```bash +lightdash login {{ lightdash_domain }} +``` - - - +where `{{ lightdash_domain }}` is the subdomain for your Lightdash instance. For example, if you login at `https://petey.lightdash.cloud`, then you would type `lightdash login petey` to pop up a login window. - - - - - To login to your Lightdash instance run the following command and provide your login email and password: + +```bash +lightdash login petey +``` + +This opens your browser to authenticate. Once authorized, you're logged in and ready to use the CLI. + + + + + + +### Flexible URL formats + +The CLI accepts your instance URL in multiple formats, all of these work: + +```bash +# Just your subdomain (recommended for Lightdash Cloud) +lightdash login your_subdomain_here + +# Full domain without protocol +lightdash login your_subdomain_here.lightdash.cloud + +# Full URL with protocol +lightdash login https://your_subdomain_here.lightdash.cloud + +# Any URL from your Lightdash instance (useful for copying from browser) +lightdash login https://your_subdomain_here.lightdash.cloud/projects/abc123/dashboards +``` + +For Lightdash Cloud users, you can simply use your subdomain (e.g., `petey` if your instance is at `petey.lightdash.cloud`). + +For self-hosted instances, you can use the full domain without the `https://` prefix - it's assumed automatically. + + +### Re-authenticate to a previous instance + +Once you've logged in, you can re-authenticate without specifying the URL: + +```bash +lightdash login +``` + +This uses your previously saved instance URL. + + + + If you prefer to use email and password instead of browser-based OAuth: ```bash - lightdash login https://{{ lightdash_domain }} + lightdash login your_subdomain_here --no-oauth ``` - where `{{ lightdash_domain }}` is the address for your running Lightdash instance. For example Lightdash cloud users in the US would type `lightdash login https://app.lightdash.cloud` if you're in Europe you'd type`lightdash login https://eu1.lightdash.cloud`. + You'll be prompted to enter your email and password. - - First, you'll need to create a new personal access token in the UI by going to Settings > Personal Access Tokens. You can't use an existing personal access token! You have to create a new one just for yourself. + + If you use single sign-on (SSO) in the browser, login with a personal access token. - {' '} + First, create a new personal access token in the UI by going to Settings > Personal Access Tokens. - Then, run the following command in your project: + Then, run the following command: ```bash - lightdash login https://{{ lightdash_domain }} --token + lightdash login your_subdomain_here --token ``` - - where `https://my-lightdash.domain.com` is the address for your running Lightdash instance. For example Lightdash cloud users in the US would type `lightdash login https://app.lightdash.cloud` if you're in Europe you'd type`lightdash login https://eu1.lightdash.cloud`. - + You can use the following environment variables to authenticate yourself on each command: * **LIGHTDASH\_API\_KEY** a personal access token you can generate in the app under the user settings @@ -67,10 +102,8 @@ Once authorized, you’ll be logged in and ready to use the CLI. Example: ```bash - LIGHTDASH_API_KEY=946fedb74003405646867dcacf1ad345 LIGHTDASH_URL="https://{{ lightdash_domain }}" LIGHTDASH_PROXY_AUTHORIZATION="Bearer " lightdash preview + LIGHTDASH_API_KEY=946fedb74003405646867dcacf1ad345 LIGHTDASH_URL="https://your_subdomain_here.lightdash.cloud" LIGHTDASH_PROXY_AUTHORIZATION="Bearer " lightdash preview ``` - - Where `{{ lightdash_domain }}` is your domain. For Lightdash Cloud users use `https://app.lightdash.cloud` @@ -108,4 +141,4 @@ Some of our favourites are: * [Testing your changes with developer previews using lightdash preview](/guides/cli/how-to-use-lightdash-preview) -* [Deploying your changes to production using lightdash deploy](/guides/cli/how-to-use-lightdash-deploy) \ No newline at end of file +* [Deploying your changes to production using lightdash deploy](/guides/cli/how-to-use-lightdash-deploy)