Authentication and Configuration

Authentication and configuration management for the Lightdash CLI, including OAuth2 login, token-based authentication, project selection, and diagnostics.

Capabilities

Login

Authenticates to a Lightdash instance using OAuth2 (browser-based) or API token.

lightdash login [url] [options]

Arguments:

• url (optional) - Lightdash server URL with flexible parsing:
  • Single words (e.g., app) → https://app.lightdash.cloud
  • Missing protocol → adds https://
  • Strips paths from URLs
  • Preserves explicit http:// protocol (for local development)

Options:

• --token <token> - Login with API access token, bypasses OAuth
• --project <project uuid> - Select project after login (must be valid UUID)
• --verbose - Enable debug logging (default: false)

Authentication Methods:

1. OAuth2 (default) - Opens browser for authentication
2. Token-based - Uses Personal Access Token or Service Account Token

Usage Examples:

# Interactive OAuth login (uses saved URL)
lightdash login

# Login to Lightdash Cloud with shorthand
lightdash login app                    # https://app.lightdash.cloud
lightdash login eu1                    # https://eu1.lightdash.cloud

# Login with full URL
lightdash login https://app.lightdash.cloud

# Login with domain only (adds https://)
lightdash login app.lightdash.cloud

# Login for local development
lightdash login http://localhost:3000

# Login with URL containing path (path is stripped)
lightdash login https://custom.lightdash.domain/projects/123
# Uses: https://custom.lightdash.domain

# Token-based login (bypasses OAuth)
lightdash login --token abc123xyz

# Login with token and select project
lightdash login --token abc123xyz --project abc-123-def-456

# Login and select project in one command (with OAuth)
lightdash login --project abc-123-def-456

# Login with verbose logging
lightdash login --verbose

Behavior:

• If URL is not provided, uses the last URL you logged into
• OAuth opens browser for authentication
• Token authentication bypasses browser (suitable for CI/CD)
• Saves authentication to ~/.config/lightdash/config.yaml
• Can select project immediately after login with --project flag

Set Project

Choose the active Lightdash project for subsequent commands.

lightdash config set-project [options]

Options:

• --name <project_name> - Set project by name (non-interactive)
• --uuid <project_uuid> - Set project by UUID (non-interactive)
• --verbose - Enable debug logging (default: false)

Constraints:

• --name and --uuid are mutually exclusive (cannot use both)

Usage Examples:

# Interactive selection (shows list of available projects)
lightdash config set-project

# Set project by name (non-interactive)
lightdash config set-project --name "Production Project"

# Set project by UUID (non-interactive)
lightdash config set-project --uuid abc-123-def-456

# With verbose logging
lightdash config set-project --verbose

Behavior:

• Without options: Shows interactive prompt with available projects
• With --name or --uuid: Non-interactive selection
• Saves selection to ~/.config/lightdash/config.yaml
• All subsequent commands use this project by default

Diagnostics

Shows diagnostic information about the CLI environment and configuration.

lightdash diagnostics [options]

Options:

• --dbt - Include dbt debug output (default: false)
• --project-dir <path> - dbt project directory for dbt debug (default: .)
• --profiles-dir <path> - dbt profiles directory for dbt debug (default: auto-detected)
• --defer - Defer to manifest in --state directory (dbt option, default: undefined)
• --no-defer - Do not defer to manifest (dbt option, default: undefined)

Information Displayed:

• Lightdash CLI version
• Node.js version (warns if not v20)
• Authentication status
• Server URL
• Organization UUID
• Project name and UUID
• Environment variable overrides (e.g., LIGHTDASH_API_KEY)
• dbt version (if --dbt flag used)
• dbt debug output (if --dbt flag used)

Usage Examples:

# Basic diagnostics
lightdash diagnostics

# Include dbt debug information
lightdash diagnostics --dbt

# dbt debug with custom project directory
lightdash diagnostics --dbt --project-dir ./my-dbt-project

# dbt debug with custom profiles directory
lightdash diagnostics --dbt --profiles-dir ~/.dbt

Use Cases:

• Troubleshooting authentication issues
• Verifying CLI and dbt installation
• Checking active project and organization
• Debugging dbt connection issues
• Confirming environment variable overrides

Configuration Storage

CLI Configuration File

Location: ~/.config/lightdash/config.yaml

Structure:

user:
  userUuid: string              # Authenticated user UUID
  anonymousUuid: string         # Anonymous tracking UUID
  organizationUuid: string      # Organization UUID
context:
  serverUrl: string             # Lightdash server URL
  project: string               # Active project UUID
  projectName: string           # Active project name
  apiKey: string                # Personal Access Token or Service Account Token
  proxyAuthorization: string    # Proxy authorization header (if needed)
  previewProject: string        # Last preview project UUID
  previewName: string           # Last preview project name
answers:
  permissionToStoreWarehouseCredentials: boolean

Notes:

• File is automatically created on first login
• Contains sensitive data (API tokens) - keep secure
• Can be manually edited if needed
• Environment variables override file values

Environment Variables

Environment variables override configuration file values:

Lightdash Variables

# Authentication
export LIGHTDASH_API_KEY="your-api-token"
export LIGHTDASH_URL="https://app.lightdash.cloud"

# Project selection
export LIGHTDASH_PROJECT="project-uuid"

# Proxy configuration
export LIGHTDASH_PROXY_AUTHORIZATION="Bearer proxy-token"

# CI mode (disables interactive prompts)
export CI="true"

Variable Priority:

1. Environment variables (highest priority)
2. Configuration file
3. Command-line flags (for URL in login command)

CI/CD Usage:

# In CI/CD pipeline, set environment variables
export LIGHTDASH_API_KEY="${SECRET_LIGHTDASH_TOKEN}"
export LIGHTDASH_PROJECT="${LIGHTDASH_PROD_PROJECT}"
export CI="true"

# Commands will use these values automatically
lightdash deploy

Authentication Methods

OAuth2 Authentication (Default)

1. Run lightdash login [url]
2. CLI opens browser to Lightdash login page
3. Authenticate in browser
4. Browser redirects back with authorization code
5. CLI exchanges code for access token
6. Token saved to config file

Advantages:

• User-friendly
• Secure (short-lived tokens)
• No manual token management

Use Cases:

• Local development
• Interactive terminal sessions

Token-Based Authentication

Use Personal Access Tokens (PAT) or Service Account Tokens:

# Create token in Lightdash UI: Settings > Personal Access Tokens

# Login with token
lightdash login --token your-token-here

# Or set environment variable
export LIGHTDASH_API_KEY="your-token-here"
lightdash deploy  # Uses token from environment

Advantages:

• Non-interactive (suitable for CI/CD)
• Long-lived tokens
• Scriptable

Use Cases:

• CI/CD pipelines
• Automation scripts
• Headless environments

Security Notes:

• Store tokens securely (use CI/CD secrets)
• Rotate tokens periodically
• Use Service Account Tokens for automation

URL Normalization

The login command normalizes URLs for convenience:

Rules:

1. Single words → https://<word>.lightdash.cloud
2. Missing protocol → adds https://
3. Paths are stripped (only host and protocol used)
4. Explicit http:// is preserved (for local development)

Troubleshooting

Authentication Errors

Error: "AuthorizationError"

• Not logged in or token expired
• Solution: Run lightdash login again

Error: "ForbiddenError"

• Don't have permission for the operation
• Solution: Contact Lightdash administrator for access

Project Selection Issues

No projects available:

• Your account has no projects
• Solution: Create a project in Lightdash UI or use lightdash deploy --create

Project not found:

• UUID is incorrect or project was deleted
• Solution: Run lightdash config set-project to select valid project

dbt Connection Issues

Use diagnostics to debug:

# Check dbt installation and configuration
lightdash diagnostics --dbt

# Verify dbt profiles
cat ~/.dbt/profiles.yml

# Test dbt connection
dbt debug

Node.js Version Warning

The CLI is optimized for Node.js v20. If using a different version, you may see warnings:

⚠️ You are using Node.js version v18.x.x. Lightdash CLI is optimized for v20 so you might experience issues.

Recommendation: Install Node.js v20 for best compatibility.