Skip to main content

​
Login

The CLI uses browser-based OAuth login by default, making authentication quick and easy.

​
Basic login

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.
This opens your browser to authenticate. Once authorized, you’re logged in and ready to use the CLI.
Authorize Application screen where Lightdash CLI requests access to your account and organization, listing read and write access, with Cancel and Authorize buttons

​
Flexible URL formats

The CLI accepts your instance URL in multiple formats, all of these work:
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:
This uses your previously saved instance URL.
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.
The Personal access tokens settings page listing existing tokens and their expiry dates, with Generate new token at top right
Then, run the following command:
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
  • LIGHTDASH_URL address for your running Lightdash instance
  • LIGHTDASH_PROXY_AUTHORIZATION if your Lightdash instance is behind a proxy like Cloud IAP you can set here Proxy-Authentication header value
Example:
These variables take precedence over the login saved by lightdash login. If lightdash login succeeds but later commands fail to authenticate, check your shell for a stale key with env | grep LIGHTDASH, then run unset LIGHTDASH_API_KEY and remove it from wherever it’s exported, such as a .env file or shell profile. When the variable is in use, lightdash diagnostics names it next to the authentication status, for example (Using LIGHTDASH_API_KEY).

​
Set active project

When you login you’ll be asked to set an active project. Your active project is just the one that you’re working on/developing in. Your organization might just have one project, so that makes your decision easy! You can change your active project by running:
Or you can use the LIGHTDASH_PROJECT environment variable to indicate what project UUID the command should use. Example:

​
Now that you’ve logged in, you’re ready to use the CLI

You can see all of the actions available on the CLI by typing this in your terminal:
Some of our favourites are: