Lightdash CLI

Lightdash CLI is a command-line interface for managing dbt (data build tool) projects and integrating them with the Lightdash business intelligence platform. It provides developers with comprehensive capabilities for compiling, validating, generating, deploying, and previewing dbt models and their associated Lightdash configurations.

Package Information

• Package Name: @lightdash/cli
• Package Type: npm
• Language: TypeScript
• Installation: npm install -g @lightdash/cli
• Binary Command: lightdash

Core Usage

Install globally:

npm install -g @lightdash/cli

Authenticate to Lightdash:

lightdash login https://app.lightdash.cloud

Basic workflow:

# Generate YAML schemas for dbt models
lightdash generate

# Compile and deploy to Lightdash
lightdash deploy

# Create preview environment for testing
lightdash preview

Architecture

The Lightdash CLI is built around several key components:

• Authentication System: OAuth2 and token-based authentication with local config storage
• dbt Integration: Executes dbt compile/run commands and parses manifest.json
• Lightdash API Client: Communicates with Lightdash server for deployment and management
• YAML Generation: Automatically generates Lightdash-compatible schema files from dbt models
• Preview Environment: Creates temporary Lightdash projects for testing changes
• Code Management: Downloads and uploads charts/dashboards as YAML code
• Warehouse Support: Direct integration with BigQuery, Snowflake, Postgres, Redshift, Databricks, Trino, and Clickhouse

Capabilities

Authentication and Configuration

Authenticate to Lightdash instances and manage project settings.

lightdash login [url]
lightdash config set-project
lightdash diagnostics

Authentication and Configuration

dbt Project Compilation

Compile dbt models into Lightdash explores with full warehouse integration.

lightdash compile [options]

Key options:

• --project-dir <path> - dbt project directory
• --select <models...> - Model selection (dbt syntax)
• --skip-warehouse-catalog - Use YML types only
• --skip-dbt-compile - Use existing manifest.json

dbt Compilation

YAML Schema Generation

Generate Lightdash YAML schema files for dbt models with automatic type detection.

lightdash generate [options]
lightdash dbt run [options]

YAML Generation

Project Deployment

Deploy compiled Lightdash projects to production or create new projects.

lightdash deploy [options]

Key options:

• --create [project_name] - Create new project
• --ignore-errors - Deploy with compilation errors
• --start-of-week <number> - Set first day of week (0-6)

Deployment

Preview Environments

Create temporary preview projects for testing changes before deploying to production.

lightdash preview [options]
lightdash start-preview --name <name> [options]
lightdash stop-preview --name <name>

Preview Environments

Project Validation

Validate Lightdash projects by running validation jobs on tables, charts, and dashboards.

lightdash validate [options]

Validation targets:

• tables - Validate table/model definitions
• charts - Validate saved charts
• dashboards - Validate dashboards

Validation

Charts and Dashboards as Code

Download and upload Lightdash charts and dashboards as YAML files for version control.

lightdash download [options]
lightdash upload [options]

Charts and Dashboards as Code

Content Refactoring

Rename models and fields across all charts and dashboards in a project.

lightdash rename [options]

Rename types:

• model - Rename a dbt model
• field - Rename a field in a model

Content Refactoring

Additional Commands

lightdash refresh              # Refresh project from git
lightdash generate-exposures   # Generate dbt exposures YAML
lightdash lint                 # Validate Lightdash Code files

Additional Commands

Environment Variables

Lightdash Configuration

• LIGHTDASH_API_KEY - API token for authentication
• LIGHTDASH_URL - Lightdash server URL
• LIGHTDASH_PROJECT - Project UUID
• LIGHTDASH_PROXY_AUTHORIZATION - Proxy authorization header

dbt Configuration

• DBT_PROJECT_DIR - Default dbt project directory (default: .)
• DBT_PROFILES_DIR - Default dbt profiles directory (default: auto-detected)
• DBT_TARGET_PATH - Override target path for dbt compilation

Other

• CI - When set to 'true', enables non-interactive mode
• AWS_SDK_JS_SUPPRESS_MAINTENANCE_MODE_MESSAGE - Automatically set to '1' by CLI to suppress Snowflake SDK warnings

Configuration Files

CLI Configuration (~/.config/lightdash/config.yaml)

Stores authentication and context information:

user:
  userUuid: string
  anonymousUuid: string
  organizationUuid: string
context:
  serverUrl: string
  project: string           # project UUID
  projectName: string
  apiKey: string           # Personal Access Token or Service Account Token
  previewProject: string
  previewName: string

Project Configuration (lightdash.config.yml)

Located in the dbt project directory:

spotlight:
  categories:
    <yamlReference>:
      label: string
      color: string
  default_visibility: string
parameters:
  <parameterName>: <parameterValue>
warehouse:
  type: postgres | bigquery | snowflake | redshift | databricks | trino | clickhouse

dbt Configuration

Standard dbt configuration files:

• dbt_project.yml - dbt project configuration
• profiles.yml - Warehouse connection profiles (in ~/.dbt/ or custom location)

Model Selection Syntax

Commands that accept --select, --models, or --exclude options support dbt's selection syntax:

• model_name - Select a single model
• model1 model2 - Select multiple models (space-separated)
• tag:tagname - Select all models with a specific tag
• +model - Select a model and all its parents
• model+ - Select a model and all its children
• +model+ - Select a model, its parents, and its children

Examples:

# Generate YAML for a single model
lightdash generate -s customers

# Generate YAML for models with the "sales" tag
lightdash generate -s tag:sales

# Compile a model and all its dependencies
lightdash compile -s +orders

Lightdash YAML Models

The CLI supports an alternative model definition format called Lightdash YAML Models:

• Define models without dbt (optional dbt-free workflow)
• Models defined in lightdash/ directory
• Type: model/v1, model/v1beta, or model
• No warehouse connection required for compilation
• Useful for warehouse-less projects (e.g., dbt Cloud CLI)

See lightdash.config.yml for warehouse type configuration when using Lightdash YAML models.

Supported Warehouses

The CLI supports the following data warehouse platforms:

• BigQuery - OAuth and Service Account authentication
• Snowflake - Automatic timestamp conversion to UTC
• Postgres - PostgreSQL databases
• Redshift - Amazon Redshift
• Databricks - OAuth support
• Trino - Trino query engine
• Clickhouse - ClickHouse databases

Common Workflows

Initial Setup

# Install CLI globally
npm install -g @lightdash/cli

# Authenticate to Lightdash
lightdash login https://app.lightdash.cloud

# Select active project
lightdash config set-project

Development Workflow

# Make changes to dbt models

# Generate YAML schemas for new/modified models
lightdash generate -s mymodel

# Create preview environment to test changes
lightdash preview --name my-feature

# Press ENTER when done to cleanup preview

CI/CD Workflow

# Set authentication via environment variable
export LIGHTDASH_API_KEY="your-token"

# Compile and validate
lightdash compile --no-warehouse-credentials
lightdash validate --preview

# Deploy to production (on main branch)
lightdash deploy --ignore-errors

Chart Management

# Download all charts and dashboards
lightdash download --nested

# Make changes to YAML files

# Upload changes back to Lightdash
lightdash upload --force

Exit Codes

• 0 - Command succeeded
• 1 - Command failed (validation errors, compilation errors, authentication errors, etc.)

Error Handling

Common error types:

• AuthorizationError - Not logged in or invalid credentials
• ForbiddenError - Permission denied for the operation
• ParseError - dbt parsing errors
• ParameterError - Invalid parameters provided
• UnexpectedServerError - Server-side errors

When errors occur, the CLI provides detailed error messages and suggestions for resolution.