Preview Environments

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

Capabilities

Preview

Creates a temporary preview project, watches for changes, and waits for user input to cleanup.

lightdash preview [options]

Inherits all compilation options (see dbt Compilation), plus:

Preview Configuration:

• --name <preview name> - Custom preview name (default: random name)
• --vars <vars> - dbt variables as JSON string
• --start-of-week <number> - First day of week for date functions: 0 (Monday) to 6 (Sunday)
• --use-dbt-list [true|false] - Use dbt list instead of dbt compile to generate manifest (default: true)
• --ignore-errors - Deploy with compilation errors (default: false)
• --table-configuration <prod|all> - Copy table configuration from production (default: 'all')
• --skip-copy-content - Don't copy content from source project (default: false)
• --disable-timestamp-conversion [true|false] - Disable timestamp conversion to UTC for Snowflake warehouses (default: false)
• --organization-credentials <name> - Use organization warehouse credentials (Enterprise Edition feature)

Note: The source code contains a duplicate definition of --disable-timestamp-conversion in the preview command (lines 471-475 and 481-485 in index.ts). This appears to be a copy-paste error in the source code.

Usage Examples:

# Create preview with random name (interactive mode)
lightdash preview

# Create preview with custom name
lightdash preview --name feature-123

# Create preview for specific models
lightdash preview --name test-orders --select orders

# Create preview without copying content
lightdash preview --skip-copy-content

# Create preview with table configuration from prod only
lightdash preview --table-configuration prod

# Create preview with start of week setting
lightdash preview --start-of-week 6  # Sunday

# Create preview with organization credentials
lightdash preview --organization-credentials "prod-warehouse"

# Create preview with custom dbt directories
lightdash preview --project-dir ./dbt --profiles-dir ./profiles

Behavior:

• Creates new preview project with unique name
• Deploys compiled explores to preview
• Watches target/manifest.json for changes
• Auto-redeploys on file changes
• Press ENTER to stop watching and cleanup preview
• Saves preview context to config file

Start Preview

Creates or updates a preview project without watching for changes (CI-friendly).

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

Inherits all compilation options (see dbt Compilation), plus:

Preview Configuration:

• --name [preview name] - [REQUIRED] Preview name (alphanumeric, hyphens, underscores)
• --vars <vars> - dbt variables as JSON string
• --start-of-week <number> - First day of week for date functions: 0-6
• --use-dbt-list [true|false] - Use dbt list instead of dbt compile (default: true)
• --ignore-errors - Deploy with compilation errors (default: false)
• --table-configuration <prod|all> - Copy table configuration from production (default: 'all')
• --skip-copy-content - Don't copy content from source project (default: false)
• --disable-timestamp-conversion [true|false] - Disable timestamp conversion to UTC for Snowflake warehouses (default: false)

Note: Unlike the preview command, start-preview does NOT support --organization-credentials. Use the regular preview command if you need organization credentials.

Usage Examples:

# Create or update preview (CI mode)
lightdash start-preview --name pr-123

# Create preview for specific models
lightdash start-preview --name feature-customers --select customers

# Create preview without content copy
lightdash start-preview --name clean-preview --skip-copy-content

# Create preview with only prod table config
lightdash start-preview --name test --table-configuration prod

# CI/CD: Create preview with environment variables
export CI=true
export LIGHTDASH_API_KEY="token"
lightdash start-preview --name ci-preview

CI/CD Integration:

When CI=true, sets GitHub Actions outputs:

• url - Preview project URL
• project_uuid - Preview project UUID

Behavior:

• Creates new preview if name doesn't exist
• Updates existing preview if name already exists
• Does NOT watch for changes (unlike preview)
• Does NOT auto-cleanup (use stop-preview to delete)
• Saves preview context to config file
• Non-interactive (suitable for CI/CD)

Stop Preview

Deletes a preview project by name.

lightdash stop-preview --name <name>

Options:

• --name [preview name] - [REQUIRED] Preview name to delete
• --verbose - Enable debug logging (default: false)

Usage Examples:

# Delete preview by name
lightdash stop-preview --name feature-123

# Delete preview with verbose output
lightdash stop-preview --name test-preview --verbose

# CI/CD: Delete preview after testing
lightdash stop-preview --name pr-${PR_NUMBER}

Behavior:

• Deletes preview project permanently
• Removes all charts and dashboards in preview
• Clears preview context from config file
• Cannot be undone

Error Handling:

• Returns error if preview doesn't exist
• Returns error if user lacks permission

Preview Workflow

Interactive Development

# 1. Make changes to dbt models
vim models/customers.sql

# 2. Create preview environment
lightdash preview --name test-customers

# Preview URL displayed:
# https://app.lightdash.cloud/projects/preview-abc-123

# 3. CLI watches for changes
# Make more changes to models...

# 4. Changes auto-deploy to preview
# Review changes in browser

# 5. Press ENTER when done
# Preview is automatically cleaned up

CI/CD Workflow

# In pull request workflow:

# 1. Start preview
lightdash start-preview --name pr-${PR_NUMBER}

# 2. Run tests against preview
lightdash validate --preview

# 3. Post preview URL to PR comments
# (Use GitHub Actions outputs)

# 4. On PR close, cleanup preview
lightdash stop-preview --name pr-${PR_NUMBER}

Preview Creation Process

1. Source Project Identification

• Uses active project as source (from config or --project)
• Source project provides:
  • Content to copy (charts, dashboards)
  • Table configuration
  • Project settings

2. Preview Project Creation

• Creates new project with preview name
• Project name format: [Preview] <name>
• Inherits organization from source project

3. Content Copying

Controlled by --skip-copy-content and --table-configuration:

With content copy (default):

• Copies all charts from source
• Copies all dashboards from source
• Copies spaces and organization

With --skip-copy-content:

• Creates empty preview
• No charts or dashboards copied
• Only explores deployed

Table configuration modes:

• all (default) - Copy all table configurations
• prod - Copy only production table configurations

4. Explore Deployment

• Compiles dbt project
• Deploys compiled explores to preview
• Applies model selection if specified

5. Context Saving

Saves to ~/.config/lightdash/config.yaml:

context:
  previewProject: preview-uuid
  previewName: preview-name

File Watching (preview command)

The preview command watches for changes and auto-redeploys:

Watched File:

• target/manifest.json (or custom --target-path)

Triggers Redeployment:

• File content changes
• File is recreated
• dbt recompiles manifest

How to Trigger:

# In another terminal, run dbt commands:
dbt compile
dbt run

# Preview automatically detects changes and redeploys

Stop Watching:

• Press ENTER in the terminal running preview
• Preview project is automatically deleted
• CLI exits

Preview Naming

Automatic Names (preview)

When --name not provided:

lightdash preview
# Creates: preview-1234567890 (random)

Custom Names

Valid characters:

• Lowercase letters: a-z
• Numbers: 0-9
• Hyphens: -
• Underscores: _

Examples:

# Good names
lightdash preview --name feature-123
lightdash preview --name test_orders
lightdash preview --name pr-456

# Invalid names (will error)
lightdash preview --name "Feature 123"  # spaces
lightdash preview --name Feature-123    # uppercase
lightdash preview --name feature/123    # slashes

Name Conflicts

If preview name already exists:

• preview - Creates with different random name
• start-preview - Updates existing preview

Table Configuration Modes

Controls what table configuration is copied from source project:

All Mode (Default)

lightdash preview --table-configuration all

Copies:

• All table visibility settings
• All field visibility settings
• All custom labels
• All table descriptions
• All field descriptions

Use when:

• Want exact copy of production
• Testing with full configuration
• Need all customizations

Prod Mode

lightdash preview --table-configuration prod

Copies:

• Only production-tagged table configurations
• Minimal configuration set

Use when:

• Want lighter preview
• Only need core tables
• Testing specific features

Skip Content Copy

Prevent copying charts and dashboards:

lightdash preview --skip-copy-content

Result:

• Preview has no charts
• Preview has no dashboards
• Only explores available
• Spaces not copied

Use when:

• Testing model changes only
• Don't need existing visualizations
• Want clean slate for testing
• Faster preview creation

Compilation Options

Preview commands inherit all compilation options:

Model Selection

# Preview only specific models
lightdash preview --select customers orders

# Preview models with tag
lightdash preview --select tag:staging

# Preview with exclusions
lightdash preview --exclude test_*

# Use predefined dbt selector
lightdash preview --selector my_selector

dbt State Management

# Use state directory for state-based selection
lightdash preview --state ./prod-state

# Defer to production for unselected nodes
lightdash preview --state ./prod-state --defer

# Don't defer (compile everything)
lightdash preview --state ./prod-state --no-defer

# Preview only modified models
lightdash preview --state ./prod-state --select state:modified+ --defer

dbt Execution Options

# Use more threads for faster compilation
lightdash preview --threads 8

# Skip dbt version check
lightdash preview --no-version-check

# Full refresh for incremental models
lightdash preview --full-refresh

Fast Preview Creation

# Skip warehouse catalog
lightdash preview --skip-warehouse-catalog

# Use existing manifest
lightdash preview --skip-dbt-compile

# Both (fastest)
lightdash preview --no-warehouse-credentials

Custom dbt Configuration

# Custom directories
lightdash preview --project-dir ./dbt --profiles-dir ./profiles

# Custom target
lightdash preview --target staging

# dbt variables
lightdash preview --vars '{"env": "dev"}'

GitHub Actions Integration

Example: Preview on PR

name: Lightdash Preview

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  preview:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '20'

      - name: Install Lightdash CLI
        run: npm install -g @lightdash/cli

      - name: Create Preview
        id: preview
        env:
          LIGHTDASH_API_KEY: ${{ secrets.LIGHTDASH_API_KEY }}
          LIGHTDASH_PROJECT: ${{ secrets.LIGHTDASH_PROJECT }}
          CI: true
        run: lightdash start-preview --name pr-${{ github.event.pull_request.number }}

      - name: Comment PR
        uses: actions/github-script@v6
        with:
          script: |
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: `Preview ready: ${{ steps.preview.outputs.url }}`
            })

Example: Cleanup on PR Close

name: Cleanup Preview

on:
  pull_request:
    types: [closed]

jobs:
  cleanup:
    runs-on: ubuntu-latest
    steps:
      - name: Install Lightdash CLI
        run: npm install -g @lightdash/cli

      - name: Stop Preview
        env:
          LIGHTDASH_API_KEY: ${{ secrets.LIGHTDASH_API_KEY }}
          CI: true
        run: lightdash stop-preview --name pr-${{ github.event.pull_request.number }}

Start of Week Configuration

Controls first day of week for week-related date functions:

--start-of-week <number>

Values:

• 0 - Monday
• 1 - Tuesday
• 2 - Wednesday
• 3 - Thursday
• 4 - Friday
• 5 - Saturday
• 6 - Sunday

Usage:

# Monday as first day
lightdash preview --start-of-week 0

# Sunday as first day
lightdash preview --start-of-week 6

Affects:

• Week truncation functions in preview
• Week-based metrics and dimensions
• Calendar displays in preview UI

Organization Credentials

Enterprise Edition feature for using shared warehouse credentials:

--organization-credentials <name>

Usage:

# Use org credentials
lightdash preview --organization-credentials "dev-warehouse"

Benefits:

• No personal warehouse credentials needed
• Centralized credential management
• Consistent access across team
• Audit trail for usage

Requirements:

• Lightdash Enterprise Edition
• Organization admin must configure credentials
• User must have permission to use credentials

Validation with Preview

Test preview before merging:

# 1. Create preview
lightdash start-preview --name test-feature

# 2. Validate preview
lightdash validate --preview

# 3. Check specific elements
lightdash validate --preview --only charts dashboards

# 4. If valid, deploy to production
lightdash deploy

# 5. Cleanup preview
lightdash stop-preview --name test-feature

Permission Requirements

Create Preview

Required permissions:

• Developer or Admin role on source project
• Project create permission (if needed)

Delete Preview

Required permissions:

• Admin role on preview project
• Or creator of the preview

Error if insufficient permissions:

ForbiddenError: You don't have permission to delete this project

Return Values

Exit Code 0: Preview command succeeded Exit Code 1: Preview command failed

Success Output (preview):

✓ Created preview project: feature-123
✓ Preview URL: https://app.lightdash.cloud/projects/abc-123
  Watching for changes... (Press ENTER to stop)

Success Output (start-preview):

✓ Created preview project: pr-456
✓ Preview URL: https://app.lightdash.cloud/projects/def-789
✓ Project UUID: def-789

Success Output (stop-preview):

✓ Deleted preview project: feature-123

Troubleshooting

Preview Creation Fails

Error: "Failed to create preview"

• Check source project exists
• Verify permissions
• Use --verbose for details

Preview Not Found

Error: "Preview project not found"

• Preview was deleted manually
• Name doesn't match existing preview
• Solution: Create new preview

File Watch Not Working

Issue: Changes not detected

• Check target path exists
• Verify manifest.json is being updated
• Try running dbt compile manually

Content Copy Fails

Error: "Failed to copy content"

• Large projects may take time
• Use --skip-copy-content as alternative
• Check network connection

Name Validation Errors

Error: "Invalid preview name"

• Only use a-z, 0-9, -, _
• No spaces or special characters
• Keep names short and descriptive

Best Practices

1. Use Descriptive Names

Good naming conventions:

# Feature branches
lightdash preview --name feature-user-auth

# Bug fixes
lightdash preview --name fix-orders-bug

# Pull requests
lightdash preview --name pr-123

2. Clean Up Previews

Don't leave previews running:

# After testing, always cleanup
lightdash stop-preview --name feature-123

3. Test Before Production

Use preview workflow:

# 1. Create preview
lightdash preview --name test-changes

# 2. Review in browser
# 3. Validate
lightdash validate --preview

# 4. If good, deploy
lightdash deploy

# 5. Cleanup preview (automatic with interactive preview)

4. Use CI/CD for Team Previews

Automate preview creation:

# On pull request, create preview
# Post URL to PR
# On PR merge, cleanup preview

5. Selective Model Preview

Preview only changed models:

# If changing orders model
lightdash preview --name test-orders --select orders

# Faster preview creation
# Focused testing

6. Skip Content for Speed

When testing models only:

# Skip content copy for faster preview
lightdash preview --skip-copy-content

7. Use Validation

Always validate previews:

lightdash validate --preview --only tables