Skip to content

Commit 2ac33a9

Browse files
mintlify[bot]mintlify[bot]
authored
Add docs for lightdash lint command (#433)
* Add documentation for lightdash lint command Generated-By: mintlify-agent * Recommend Lightdash Skills as preferred approach for AI tooling Generated-By: mintlify-agent --------- Co-authored-by: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com>
1 parent 15c1037 commit 2ac33a9

3 files changed

Lines changed: 248 additions & 0 deletions

File tree

‎docs.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -167,6 +167,7 @@
167167
"group": "Developer guides",
168168
"icon": "list-check",
169169
"pages": [
170+
"guides/cli/how-to-use-lightdash-lint",
170171
"guides/developer/agent-skills",
171172
"guides/developer/dbt-model-best-practices",
172173
"guides/developer/preview-projects",

‎guides/cli/how-to-use-lightdash-lint.mdx‎

Lines changed: 182 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,182 @@
1+
---
2+
title: "How to use lightdash lint"
3+
sidebarTitle: "Linting your code"
4+
description: "Validate your Lightdash Code files against JSON schemas before deploying to catch errors early."
5+
---
6+
7+
The `lightdash lint` command validates your Lightdash Code files (models, charts, dashboards) against JSON schemas. This helps you catch configuration errors before deploying changes.
8+
9+
## Why use linting?
10+
11+
Linting is especially valuable when:
12+
13+
- **Developing with AI tools** - AI copilots like Cursor, Claude Code, or Kilo Code can generate Lightdash YAML files, but may produce invalid configurations. Running `lightdash lint` after each change validates the output.
14+
- **Working with dashboards as code** - When editing chart or dashboard YAML files manually, linting catches typos and structural errors.
15+
- **CI/CD pipelines** - Add linting to your deployment workflow to prevent invalid configurations from reaching production.
16+
17+
## Basic usage
18+
19+
Validate all Lightdash Code files in the current directory:
20+
21+
```bash
22+
lightdash lint
23+
```
24+
25+
Validate a specific file:
26+
27+
```bash
28+
lightdash lint --path ./lightdash/charts/revenue-by-month.yml
29+
```
30+
31+
Validate a specific directory:
32+
33+
```bash
34+
lightdash lint --path ./lightdash
35+
```
36+
37+
## Output formats
38+
39+
### CLI output (default)
40+
41+
The default output shows errors in a human-readable format with file paths and line numbers:
42+
43+
```bash
44+
lightdash lint
45+
```
46+
47+
Example output:
48+
49+
```
50+
✗ ./lightdash/charts/my-chart.yml
51+
Line 15: metricQuery.dimensions must be array
52+
53+
Found 1 error in 1 file
54+
```
55+
56+
### Verbose output
57+
58+
Use `--verbose` to see all validated files, including those that passed:
59+
60+
```bash
61+
lightdash lint --verbose
62+
```
63+
64+
### SARIF JSON output
65+
66+
For CI/CD integration, use SARIF (Static Analysis Results Interchange Format) output:
67+
68+
```bash
69+
lightdash lint --format json
70+
```
71+
72+
This outputs results in [SARIF format](https://sarifweb.azurewebsites.net/), which is supported by GitHub Actions, VS Code, and other tools.
73+
74+
## What gets validated
75+
76+
The lint command validates three types of files against their JSON schemas:
77+
78+
| File type | Identified by | Schema |
79+
|-----------|---------------|--------|
80+
| Models | `type: model` in YAML | [model-as-code-1.0.json](https://github.com/lightdash/lightdash/blob/main/packages/common/src/schemas/json/model-as-code-1.0.json) |
81+
| Charts | `metricQuery` property | [chart-as-code-1.0.json](https://github.com/lightdash/lightdash/blob/main/packages/common/src/schemas/json/chart-as-code-1.0.json) |
82+
| Dashboards | `tiles` property | [dashboard-as-code-1.0.json](https://github.com/lightdash/lightdash/blob/main/packages/common/src/schemas/json/dashboard-as-code-1.0.json) |
83+
84+
The command automatically detects the file type based on its content and applies the appropriate schema.
85+
86+
## Using lint with AI coding tools
87+
88+
<Note>
89+
**Recommended: Install Lightdash Skills first.** Before manually configuring your AI tool, run `lightdash install-skills` to install the [Lightdash Skills](/get-started/develop-in-lightdash/install-skills). The skills already know to use `lightdash lint` for validation, so you don't need to configure anything manually.
90+
</Note>
91+
92+
If you're using Lightdash Skills, your AI copilot will automatically run `lightdash lint` to validate YAML files as part of its workflow. The skills include best practices for schema validation built-in.
93+
94+
### Manual configuration (without skills)
95+
96+
If you're not using Lightdash Skills, you can manually configure your AI copilot to use linting:
97+
98+
1. **Prompt the AI to run lint after changes** - Add instructions like "Always run `lightdash lint` after making changes to validate the YAML."
99+
100+
2. **Provide schema references** - Give your AI tool the schema URLs so it understands the expected format:
101+
- Models: `https://raw.githubusercontent.com/lightdash/lightdash/main/packages/common/src/schemas/json/model-as-code-1.0.json`
102+
- Charts: `https://raw.githubusercontent.com/lightdash/lightdash/main/packages/common/src/schemas/json/chart-as-code-1.0.json`
103+
- Dashboards: `https://raw.githubusercontent.com/lightdash/lightdash/main/packages/common/src/schemas/json/dashboard-as-code-1.0.json`
104+
105+
3. **Iterate on errors** - When lint reports errors, have the AI fix them before proceeding.
106+
107+
<Tip>
108+
AI tools can run `lightdash lint` to validate their own output. This creates a feedback loop that catches errors automatically.
109+
</Tip>
110+
111+
## CI/CD integration
112+
113+
Add linting to your CI/CD pipeline to prevent invalid configurations from being deployed.
114+
115+
### GitHub Actions example
116+
117+
```yaml
118+
name: Validate Lightdash Code
119+
120+
on:
121+
pull_request:
122+
paths:
123+
- 'lightdash/**'
124+
125+
jobs:
126+
lint:
127+
runs-on: ubuntu-latest
128+
steps:
129+
- uses: actions/checkout@v3
130+
131+
- name: Install Lightdash CLI
132+
run: npm install -g @lightdash/cli
133+
134+
- name: Lint Lightdash Code files
135+
run: lightdash lint --path ./lightdash
136+
```
137+
138+
### Using SARIF with GitHub Code Scanning
139+
140+
To integrate lint results with GitHub's code scanning:
141+
142+
```yaml
143+
- name: Lint with SARIF output
144+
run: lightdash lint --format json > lint-results.sarif
145+
146+
- name: Upload SARIF results
147+
uses: github/codeql-action/upload-sarif@v2
148+
with:
149+
sarif_file: lint-results.sarif
150+
```
151+
152+
## Common errors and fixes
153+
154+
### Missing required properties
155+
156+
```
157+
metricQuery.exploreName is required
158+
```
159+
160+
**Fix:** Add the missing property to your YAML file.
161+
162+
### Invalid property type
163+
164+
```
165+
metricQuery.dimensions must be array
166+
```
167+
168+
**Fix:** Ensure the property value matches the expected type.
169+
170+
### Unknown properties
171+
172+
```
173+
should NOT have additional property 'unknownField'
174+
```
175+
176+
**Fix:** Remove the unrecognized property or check for typos.
177+
178+
## Related
179+
180+
- [Lightdash YAML](/guides/lightdash-yaml) - Define your semantic layer in YAML without dbt
181+
- [Dashboards as code](/guides/developer/dashboards-as-code) - Manage charts and dashboards as YAML files
182+
- [Lightdash CLI reference](/references/lightdash-cli#lightdash-lint) - Full command reference

‎references/lightdash-cli.mdx‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -123,6 +123,7 @@ For examples and command-specific options, click through the command in the tabl
123123
|[`lightdash rename`](/references/lightdash-cli#lightdash-rename) | Rename model or field names across all your Lightdash content |
124124
|[`lightdash diagnostics`](/references/lightdash-cli#lightdash-diagnostics) | Show diagnostic information about the CLI environment |
125125
|[`lightdash sql`](/references/lightdash-cli#lightdash-sql) | Run raw SQL query against the warehouse using project credentials |
126+
|[`lightdash lint`](/references/lightdash-cli#lightdash-lint) | Validate Lightdash Code files against JSON schemas |
126127
---
127128

128129
### `lightdash login`
@@ -821,6 +822,70 @@ Run a query with verbose output to see detailed progress:
821822
lightdash sql "SELECT customer_id, SUM(amount) FROM orders GROUP BY 1" -o revenue.csv --verbose
822823
```
823824

825+
### `lightdash lint`
826+
827+
Validates Lightdash Code files (models, charts, dashboards) against JSON schemas. This command checks that your YAML files conform to the expected structure before you deploy.
828+
829+
```console
830+
lightdash lint [options]
831+
```
832+
833+
This command does not support using dbt options.
834+
835+
**Options:**
836+
837+
- `-p, --path <path>`
838+
- Path to a file or directory to lint
839+
- (default: current directory)
840+
- `--verbose`
841+
- (default: false)
842+
- Show detailed validation output including all validated files
843+
- `-f, --format <format>`
844+
- Output format: `cli` (default) or `json` (SARIF format)
845+
- (default: "cli")
846+
847+
**Validated file types:**
848+
849+
The lint command validates three types of Lightdash Code files:
850+
851+
| File type | Schema | Description |
852+
|-----------|--------|-------------|
853+
| Models | [model-as-code-1.0.json](https://github.com/lightdash/lightdash/blob/main/packages/common/src/schemas/json/model-as-code-1.0.json) | Lightdash YAML model definitions |
854+
| Charts | [chart-as-code-1.0.json](https://github.com/lightdash/lightdash/blob/main/packages/common/src/schemas/json/chart-as-code-1.0.json) | Charts downloaded as code |
855+
| Dashboards | [dashboard-as-code-1.0.json](https://github.com/lightdash/lightdash/blob/main/packages/common/src/schemas/json/dashboard-as-code-1.0.json) | Dashboards downloaded as code |
856+
857+
**Examples:**
858+
859+
Validate all Lightdash Code files in the current directory:
860+
861+
```bash
862+
lightdash lint
863+
```
864+
865+
Validate a single chart file:
866+
867+
```bash
868+
lightdash lint --path ./lightdash/charts/my-chart.yml
869+
```
870+
871+
Validate files in a specific directory:
872+
873+
```bash
874+
lightdash lint --path ./lightdash
875+
```
876+
877+
Show detailed validation output:
878+
879+
```bash
880+
lightdash lint --verbose
881+
```
882+
883+
Output results in SARIF JSON format (useful for CI/CD integration):
884+
885+
```bash
886+
lightdash lint --format json
887+
```
888+
824889
---
825890

826891
## dbt options

0 commit comments

Comments
 (0)