Skip to content

Update CLI login documentation with improved authentication flow #282

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

Draft
owlas wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

Update CLI login documentation with improved authentication flow #282

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
84 changes: 53 additions & 31 deletions guides/cli/cli-authentication.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,56 +6,80 @@ icon: "key"

## Login

<AccordionGroup>
<Accordion title="1. You can login on the CLI from your browser using OAuth2.">
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`.
```bash
lightdash login analytics
```

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.
This opens your browser to authenticate. Once authorized, you're logged in and ready to use the CLI.

Once authorized, you’ll be logged in and ready to use the CLI.
<Frame>
<img src="images/oauth-authorize.png" alt="" />
</Frame>

<Frame>
<img src="images/oauth-authorize.png" alt="" />
</Frame>
### Flexible URL formats


</Accordion>

<Accordion title="2. If you use your email + password in the browser, login with your email and password.">
To login to your Lightdash instance run the following command and provide your login email and password:
The CLI accepts your instance URL in multiple formats - all of these work:

```bash
# Just your subdomain (recommended for Lightdash Cloud)
lightdash login analytics

# Full domain without protocol
lightdash login analytics.lightdash.cloud

# Full URL with protocol
lightdash login https://analytics.lightdash.cloud

# Any URL from your Lightdash instance (useful for copying from browser)
lightdash login https://analytics.lightdash.cloud/projects/abc123/dashboards
```

For Lightdash Cloud users, you can simply use your subdomain (e.g., `analytics` if your instance is at `analytics.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.

<AccordionGroup>
<Accordion title="Login with email and password">
If you prefer to use email and password instead of browser-based OAuth:

```bash
lightdash login https://{{ lightdash_domain }}
lightdash login analytics --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.
</Accordion>

<Accordion title="3. If you use single sign-on (SSO) in the browser, login with a personal access token.">
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.
<Accordion title="Login with a personal access token (for SSO users)">
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.

<Frame>
<img src="/images/guides/cli/personal-access-token-9ed8a8c2b16edc5ee745c4909d4093d3.png" alt="" />
</Frame>

Then, run the following command in your project:
Then, run the following command:

```bash
lightdash login https://{{ lightdash_domain }} --token
lightdash login analytics --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`.
</Accordion>

<Accordion title="4. If you're running in a CI/CD pipeline, login with environment variables">
<Accordion title="Login with environment variables (for CI/CD)">
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
Expand All @@ -67,10 +91,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 <JWT_TOKEN>" lightdash preview
LIGHTDASH_API_KEY=946fedb74003405646867dcacf1ad345 LIGHTDASH_URL="https://analytics.lightdash.cloud" LIGHTDASH_PROXY_AUTHORIZATION="Bearer <JWT_TOKEN>" lightdash preview
```

Where `{{ lightdash_domain }}` is your domain. For Lightdash Cloud users use `https://app.lightdash.cloud`
</Accordion>
</AccordionGroup>

Expand Down Expand Up @@ -108,4 +130,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)
* [Deploying your changes to production using lightdash deploy](/guides/cli/how-to-use-lightdash-deploy)