or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

additional.md authentication.md code-management.md compilation.md deployment.md generation.md index.md preview.md refactoring.md validation.md

tile.json

Charts and Dashboards as Code

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

Capabilities

Download

Downloads charts and dashboards from Lightdash as YAML files (Lightdash Code).

lightdash download [options]

Options:

Content Selection:

-c, --charts <charts...> - Chart slugs, UUIDs, or URLs to download (default: all charts, space-separated)
-d, --dashboards <dashboards...> - Dashboard slugs, UUIDs, or URLs to download (default: all dashboards, space-separated)

Download Configuration:

-p, --path <path> - Custom download path (default: ./lightdash)
--nested - Use nested folder structure by project/space (default: false, flat structure)
-l, --language-map - Generate language translation maps (default: false)
--project <project uuid> - Project UUID to download from (overrides active project)
--verbose - Enable debug logging (default: false)

Usage Examples:

# Download all charts and dashboards (flat structure)
lightdash download

# Download to custom path
lightdash download --path ./my-lightdash-code

# Download with nested folder structure
lightdash download --nested

# Download specific charts by slug
lightdash download --charts monthly-revenue customer-segmentation

# Download specific dashboards by slug
lightdash download --dashboards executive-dashboard sales-overview

# Download both specific charts and dashboards
lightdash download --charts revenue-chart --dashboards exec-dashboard

# Download by UUID
lightdash download --charts abc-123-def-456

# Download by URL
lightdash download --charts https://app.lightdash.cloud/saved/abc-123

# Download with language translation maps
lightdash download --language-map

# Download from specific project
lightdash download --project abc-123-def-456

# Download with verbose output
lightdash download --verbose

ID Formats Supported:

Slug: my-chart-name
UUID: abc-123-def-456
URL: https://app.lightdash.cloud/saved/abc-123

Upload

Uploads charts and dashboards from YAML files to Lightdash.

lightdash upload [options]

Options:

Content Selection:

-c, --charts <charts...> - Chart slugs to force upload (default: uploads all, space-separated)
-d, --dashboards <dashboards...> - Dashboard slugs to force upload (default: uploads all, space-separated)

Upload Configuration:

-p, --path <path> - Custom path to upload from (default: ./lightdash)
--force - Force upload even if content hasn't changed (default: false)
--project <project uuid> - Project UUID to upload to (overrides active project)
--verbose - Enable debug logging (default: false)

Space Management:

--skip-space-create - Don't create spaces if missing (default: false, creates spaces)
--public - Create new spaces as public (default: false, creates private spaces)

Dashboard Options:

--include-charts - Include chart updates when uploading dashboards (default: false)

Usage Examples:

# Upload all charts and dashboards from default path
lightdash upload

# Upload from custom path
lightdash upload --path ./my-lightdash-code

# Force upload all (ignore change detection)
lightdash upload --force

# Upload specific charts by slug
lightdash upload --charts monthly-revenue customer-segmentation

# Upload specific dashboards by slug
lightdash upload --dashboards executive-dashboard

# Upload both specific charts and dashboards
lightdash upload --charts revenue --dashboards executive

# Upload to specific project
lightdash upload --project abc-123-def-456

# Upload without creating missing spaces
lightdash upload --skip-space-create

# Upload and create spaces as public
lightdash upload --public

# Upload dashboards and their charts
lightdash upload --dashboards exec-dashboard --include-charts

# Upload with verbose output
lightdash upload --verbose

File Structure

Flat Structure (Default)

lightdash download

Creates:

./lightdash/
├── charts/
│   ├── monthly-revenue.yml
│   ├── customer-segmentation.yml
│   └── order-analysis.yml
└── dashboards/
    ├── executive-dashboard.yml
    └── sales-overview.yml

Characteristics:

All charts in single charts/ directory
All dashboards in single dashboards/ directory
No space organization
Simple structure
Easy to browse

Use when:

Small number of charts/dashboards
Prefer simple organization
Don't need space separation

Nested Structure

lightdash download --nested

Creates:

./lightdash/
├── charts/
│   ├── Sales Space/
│   │   ├── monthly-revenue.yml
│   │   └── customer-segmentation.yml
│   └── Finance Space/
│       └── payment-analysis.yml
└── dashboards/
    ├── Executive/
    │   └── executive-dashboard.yml
    └── Sales/
        └── sales-overview.yml

Characteristics:

Charts organized by space
Dashboards organized by space
Mirrors Lightdash space structure
Better organization for large projects

Use when:

Many charts/dashboards
Multiple spaces in project
Want to maintain space organization
Team-based organization

YAML File Format

Chart YAML

version: 1
name: Monthly Revenue
slug: monthly-revenue
space: Sales Space
description: Track monthly revenue trends
updatedAt: '2024-01-15T10:30:00Z'
updatedBy: user@example.com
metricQuery:
  exploreName: orders
  dimensions:
    - orders_order_date_month
  metrics:
    - orders_total_revenue
  filters:
    dimensions:
      - id: orders_status
        target:
          fieldId: orders_status
        operator: equals
        values:
          - completed
  sorts:
    - fieldId: orders_order_date_month
      descending: false
  limit: 100
chartConfig:
  type: cartesian
  config:
    layout:
      xField: orders_order_date_month
      yField:
        - orders_total_revenue
    eChartsConfig:
      series:
        - type: bar

Dashboard YAML

version: 1
name: Executive Dashboard
slug: executive-dashboard
space: Executive
description: Key business metrics at a glance
updatedAt: '2024-01-15T10:30:00Z'
updatedBy: user@example.com
tiles:
  - uuid: tile-1
    type: saved_chart
    properties:
      savedChartUuid: monthly-revenue-uuid
      title: Monthly Revenue
    x: 0
    y: 0
    h: 4
    w: 6
  - uuid: tile-2
    type: saved_chart
    properties:
      savedChartUuid: customer-count-uuid
      title: Total Customers
    x: 6
    y: 0
    h: 4
    w: 6
filters:
  dimensions:
    - id: date_range
      target:
        fieldId: orders_order_date
      operator: inThePast
      values:
        - 90
      settings:
        unitOfTime: days

Download Workflow

1. Full Download

Download everything for version control:

# Download all content
lightdash download --nested

# Commit to git
git add lightdash/
git commit -m "Snapshot Lightdash content"
git push

2. Selective Download

Download specific items:

# Download specific chart
lightdash download --charts monthly-revenue

# Download multiple dashboards
lightdash download --dashboards exec-dashboard sales-dashboard

3. Update Local Copy

Sync changes from Lightdash:

# Re-download to get latest changes
lightdash download --force

# Review changes
git diff lightdash/

# Commit if desired
git add lightdash/
git commit -m "Update Lightdash content"

Upload Workflow

1. Modify YAML Files

Edit downloaded YAML files:

# Edit chart configuration
vim lightdash/charts/monthly-revenue.yml

# Edit dashboard layout
vim lightdash/dashboards/executive-dashboard.yml

2. Upload Changes

# Upload all changes
lightdash upload

# Or upload specific files
lightdash upload --charts monthly-revenue

3. Version Control Integration

# Create feature branch
git checkout -b update-dashboard

# Modify YAML files
vim lightdash/dashboards/executive-dashboard.yml

# Commit changes
git add lightdash/
git commit -m "Update executive dashboard layout"

# Push and create PR
git push origin update-dashboard

# After review, upload to Lightdash
lightdash upload --dashboards executive-dashboard

Change Detection

Upload automatically detects changes:

Unchanged Content

lightdash upload
# Output: No changes detected, skipping upload

Changed Content

# Modify chart YAML
vim lightdash/charts/revenue.yml

# Upload detects changes
lightdash upload
# Output: Uploading 1 changed chart...

Force Upload

Override change detection:

# Upload even if no changes detected
lightdash upload --force

Use when:

Recreating charts/dashboards
Fixing sync issues
Ensuring consistency

Space Management

Automatic Space Creation

By default, upload creates missing spaces:

# If "Sales Space" doesn't exist, it's created
lightdash upload --charts sales-chart

Skip Space Creation

Fail if space doesn't exist:

# Error if space missing
lightdash upload --skip-space-create

Use when:

Want strict space control
Prevent accidental space creation
Enforce existing space usage

Space Visibility

Control visibility of newly created spaces:

# Create spaces as private (default)
lightdash upload

# Create spaces as public
lightdash upload --public

Private spaces:

Only accessible to specific users
Must be explicitly shared
Better for sensitive content

Public spaces:

Accessible to all project members
Good for shared content
Better for collaboration

Language Translation Maps

Generate translation files for internationalization:

lightdash download --language-map

Creates additional files:

./lightdash/
├── charts/
│   ├── monthly-revenue.yml
│   └── monthly-revenue.i18n.yml    # Translation map
└── dashboards/
    ├── executive-dashboard.yml
    └── executive-dashboard.i18n.yml # Translation map

Translation map format:

translations:
  en:
    name: Monthly Revenue
    description: Track monthly revenue trends
  es:
    name: Ingresos Mensuales
    description: Seguimiento de tendencias de ingresos mensuales
  fr:
    name: Revenus Mensuels
    description: Suivi des tendances des revenus mensuels

Use when:

Supporting multiple languages
Internationalizing content
Managing translations separately

Dashboard Chart Inclusion

Default Behavior

# Upload dashboard only
lightdash upload --dashboards executive-dashboard
# Charts referenced by dashboard are NOT updated

Include Charts

# Upload dashboard AND its charts
lightdash upload --dashboards executive-dashboard --include-charts

Use when:

Dashboard and charts changed together
Want atomic updates
Ensuring dashboard-chart consistency

Identifying Content

Multiple ways to specify charts/dashboards:

By Slug (Recommended)

lightdash download --charts monthly-revenue
lightdash upload --charts monthly-revenue

Advantages:

Human-readable
Stable across environments
Easy to remember

By UUID

lightdash download --charts abc-123-def-456

Use when:

Programmatic access
Handling renamed content
Exact identification needed

By URL

lightdash download --charts https://app.lightdash.cloud/saved/abc-123

Use when:

Copying from browser
Sharing specific content
Quick downloads

CI/CD Integration

Download in CI

name: Backup Lightdash Content

on:
  schedule:
    - cron: '0 2 * * *'  # Daily at 2 AM

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

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

      - name: Download Content
        env:
          LIGHTDASH_API_KEY: ${{ secrets.LIGHTDASH_API_KEY }}
          LIGHTDASH_PROJECT: ${{ secrets.LIGHTDASH_PROJECT }}
          CI: true
        run: lightdash download --nested

      - name: Commit Changes
        run: |
          git config user.name "GitHub Actions"
          git config user.email "actions@github.com"
          git add lightdash/
          git diff --quiet && git diff --staged --quiet || git commit -m "Backup Lightdash content"
          git push

Upload in CI

name: Deploy Lightdash Content

on:
  push:
    branches: [main]
    paths:
      - 'lightdash/**'

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

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

      - name: Upload Content
        env:
          LIGHTDASH_API_KEY: ${{ secrets.LIGHTDASH_API_KEY }}
          LIGHTDASH_PROJECT: ${{ secrets.LIGHTDASH_PROJECT }}
          CI: true
        run: lightdash upload

Use Cases

1. Version Control

Track chart and dashboard changes:

# Initial download
lightdash download --nested
git add lightdash/
git commit -m "Initial Lightdash snapshot"

# Make changes in UI
# Re-download
lightdash download --nested
git diff lightdash/
git commit -m "Updated revenue chart"

2. Team Collaboration

Share chart configurations:

# Developer A: Create chart
lightdash download --charts new-feature-chart
git add lightdash/charts/new-feature-chart.yml
git commit -m "Add new feature chart"
git push

# Developer B: Pull and upload
git pull
lightdash upload --charts new-feature-chart

3. Environment Promotion

Move content between environments:

# Download from dev
export LIGHTDASH_PROJECT="dev-project-uuid"
lightdash download --nested --path ./dev-content

# Upload to staging
export LIGHTDASH_PROJECT="staging-project-uuid"
lightdash upload --path ./dev-content

# Upload to production
export LIGHTDASH_PROJECT="prod-project-uuid"
lightdash upload --path ./dev-content

4. Backup and Recovery

Regular backups:

# Automated backup script
#!/bin/bash
DATE=$(date +%Y%m%d)
lightdash download --path ./backups/lightdash-$DATE
tar -czf lightdash-backup-$DATE.tar.gz ./backups/lightdash-$DATE

Recovery:

# Restore from backup
tar -xzf lightdash-backup-20240115.tar.gz
lightdash upload --path ./backups/lightdash-20240115 --force

5. Content Review

Review changes before applying:

# Download changes from UI
lightdash download

# Review diffs
git diff lightdash/

# If approved, commit
git add lightdash/
git commit -m "Approved dashboard updates"

# If not approved, discard
git checkout lightdash/

6. Bulk Modifications

Programmatically modify content:

# Download all
lightdash download --nested

# Modify with script
python scripts/update-chart-colors.py lightdash/charts/

# Upload changes
lightdash upload --force

Permission Requirements

Download

Required permissions:

Viewer or higher role on project
Read access to charts and dashboards

Upload

Required permissions:

Developer or higher role on project
Write access to project
Permission to create spaces (if creating new spaces)

Error if insufficient permissions:

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

Return Values

Exit Code 0: Command succeeded Exit Code 1: Command failed

Success Output (Download):

✓ Downloaded 25 charts
✓ Downloaded 5 dashboards
✓ Files saved to ./lightdash

Success Output (Upload):

✓ Uploaded 3 changed charts
✓ Uploaded 1 changed dashboard
✓ Created 1 space

Troubleshooting

Download Fails

Error: "Failed to download content"

Check authentication
Verify project access
Use --verbose for details

Upload Fails

Error: "Failed to upload content"

Check write permissions
Verify YAML syntax
Check referenced UUIDs exist

Invalid YAML

Error: "Invalid YAML format"

Check YAML syntax
Validate required fields
Use linter: lightdash lint --path lightdash/

Missing Space

Error: "Space not found"

Space was deleted
Use --skip-space-create=false to create
Or manually create space in UI

Chart Not Found

Error: "Chart not found"

Chart was deleted
UUID is incorrect
Use slug instead of UUID

Path Issues

Error: "Path not found"

Directory doesn't exist
Create directory first
Check path spelling

Best Practices

1. Use Nested Structure for Large Projects

lightdash download --nested
# Better organization
# Easier to navigate

2. Commit to Version Control

# Always version control
lightdash download --nested
git add lightdash/
git commit -m "Snapshot Lightdash content"

3. Use Descriptive Commit Messages

git commit -m "Update revenue chart to include Q4 data"
git commit -m "Fix dashboard layout for mobile"
git commit -m "Add new customer segmentation chart"

4. Review Before Uploading

# Download current state
lightdash download

# Review changes
git diff lightdash/

# Upload if approved
lightdash upload

5. Automate Backups

# Regular downloads
# Store in version control
# Archive periodically

6. Test in Preview

# Upload to preview first
export LIGHTDASH_PROJECT="preview-uuid"
lightdash upload

# Validate
lightdash validate --only charts dashboards

# If good, upload to production
export LIGHTDASH_PROJECT="prod-uuid"
lightdash upload

7. Use Linting

# Validate YAML before uploading
lightdash lint --path lightdash/

# Fix any errors
# Then upload
lightdash upload

8. Document Changes

# CHANGELOG.md

## 2024-01-15
- Updated monthly revenue chart to use new metric
- Fixed executive dashboard layout
- Added customer segmentation chart to sales space

Version

Tile

Files

code-management.md.css-3qkkll{font-size:var(--chakra-font-sizes-sm);font-weight:var(--chakra-font-weights-normal);color:var(--chakra-colors-gray-300);}docs/

Charts and Dashboards as Code

Capabilities

Download

Upload

File Structure

Flat Structure (Default)

Nested Structure

YAML File Format

Chart YAML

Dashboard YAML

Download Workflow

1. Full Download

2. Selective Download

3. Update Local Copy

Upload Workflow

1. Modify YAML Files

2. Upload Changes

3. Version Control Integration

Change Detection

Unchanged Content

Changed Content

Force Upload

Space Management

Automatic Space Creation

Skip Space Creation

Space Visibility

Language Translation Maps

Dashboard Chart Inclusion

Default Behavior

Include Charts

Identifying Content

By Slug (Recommended)

By UUID

By URL

CI/CD Integration

Download in CI

Upload in CI

Use Cases

1. Version Control

2. Team Collaboration

3. Environment Promotion

4. Backup and Recovery

5. Content Review

6. Bulk Modifications

Permission Requirements

Download

Upload

Return Values

Troubleshooting

Download Fails

Upload Fails

Invalid YAML

Missing Space

Chart Not Found

Path Issues

Best Practices

1. Use Nested Structure for Large Projects

2. Commit to Version Control

3. Use Descriptive Commit Messages

4. Review Before Uploading

5. Automate Backups

6. Test in Preview

7. Use Linting

8. Document Changes

code-management.mddocs/