The qyra lint command validates your Qyra Code files (models, charts, dashboards) against JSON schemas. This helps you catch configuration errors before deploying changes.

Why use linting?

Linting is especially valuable when:

• Developing with AI tools - AI copilots like Cursor, Claude Code, or Kilo Code can generate Qyra YAML files, but may produce invalid configurations. Running qyra lint after each change validates the output.
• Working with dashboards as code - When editing chart or dashboard YAML files manually, linting catches typos and structural errors.
• CI/CD pipelines - Add linting to your deployment workflow to prevent invalid configurations from reaching production.

Basic usage

Validate all Qyra Code files in the current directory:

qyra lint

Validate a specific file:

qyra lint --path ./qyra/charts/revenue-by-month.yml

Validate a specific directory:

qyra lint --path ./qyra

Output formats

CLI output (default)

The default output shows errors in a human-readable format with file paths and line numbers:

qyra lint

Example output:

✗ ./qyra/charts/my-chart.yml
  Line 15: metricQuery.dimensions must be array

Found 1 error in 1 file

Errors vs. warnings

qyra lint reports two severities:

• Errors (red ✗) — schema validation failures. These cause the command to exit with a non-zero status, so they fail CI.
• Warnings (yellow ⚠) — non-fatal issues that don't block deployment but signal a configuration that's likely to behave unexpectedly. Warnings do not affect the exit code.

Verbose output

Use --verbose to see all validated files, including those that passed:

qyra lint --verbose

SARIF JSON output

For CI/CD integration, use SARIF (Static Analysis Results Interchange Format) output:

qyra lint --format json

This outputs results in SARIF format, which is supported by GitHub Actions, VS Code, and other tools.

What gets validated

The lint command validates three types of files against their JSON schemas:

The command automatically detects the file type based on its content and applies the appropriate schema.

Using lint with AI coding tools

If you're using Qyra Skills, your AI copilot will automatically run qyra lint to validate YAML files as part of its workflow. The skills include best practices for schema validation built-in.

Manual configuration (without skills)

If you're not using Qyra Skills, you can manually configure your AI copilot to use linting:

1. Prompt the AI to run lint after changes - Add instructions like "Always run qyra lint after making changes to validate the YAML."

2. Provide schema references - Give your AI tool the schema URLs so it understands the expected format:

   • Models: https://raw.githubusercontent.com/quanvio/qyra/main/packages/common/src/schemas/json/model-as-code-1.0.json
   • Charts: https://raw.githubusercontent.com/quanvio/qyra/main/packages/common/src/schemas/json/chart-as-code-1.0.json
   • Dashboards: https://raw.githubusercontent.com/quanvio/qyra/main/packages/common/src/schemas/json/dashboard-as-code-1.0.json

3. Iterate on errors - When lint reports errors, have the AI fix them before proceeding.

CI/CD integration

Add linting to your CI/CD pipeline to prevent invalid configurations from being deployed.

GitHub Actions example

name: Validate Qyra Code

on:
  pull_request:
    paths:
      - 'qyra/**'

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

      - name: Install Qyra CLI
        run: npm install -g qyra-cli

      - name: Lint Qyra Code files
        run: qyra lint --path ./qyra

Using SARIF with GitHub Code Scanning

To integrate lint results with GitHub's code scanning:

- name: Lint with SARIF output
  run: qyra lint --format json > lint-results.sarif

- name: Upload SARIF results
  uses: github/codeql-action/upload-sarif@v2
  with:
    sarif_file: lint-results.sarif

Common errors and fixes

Missing required properties

metricQuery.exploreName is required

Fix: Add the missing property to your YAML file.

Invalid property type

metricQuery.dimensions must be array

Fix: Ensure the property value matches the expected type.

Unknown properties

should NOT have additional property 'unknownField'

Fix: Remove the unrecognized property or check for typos.

Related

• Qyra YAML - Define your semantic layer in YAML without dbt
• Dashboards as code - Manage charts and dashboards as YAML files
• Qyra CLI reference - Full command reference