@duckcodeailabs/dql-cli

Official command-line interface for DQL.

Use the CLI to scaffold projects, validate blocks, preview charts locally, and build static bundles without DuckCode Studio.

Install

Use Node 20 or newer. If you change Node versions after installing native database drivers, reinstall those project-local dependencies for the active runtime.

npm i -D @duckcodeailabs/dql-cli@latest
npx dql --version

Project-local installation is recommended for existing repositories. npm puts the executable in node_modules/.bin, so use npx dql ... or the repository's npm run ... scripts. A bare shell command requires a global installation:

npm i -g @duckcodeailabs/dql-cli@latest
dql --version

Or run it without adding a dependency:

npx @duckcodeailabs/dql-cli --help

From this repo, you can also run:

pnpm exec dql --help

Quick Start

These commands use the project-local CLI installed by the starter templates.

npx create-dql-app@latest my-dql-project
cd my-dql-project
npm install
npm run doctor
npm run notebook

If you want the dbt-integrated starter instead, use the Jaffle Shop semantic-layer course repo:

git clone https://github.com/dbt-labs/Semantic-Layer-Online-Course.git jaffle-shop
cd jaffle-shop
pip install dbt-duckdb && dbt deps && dbt build --profiles-dir .
npm i -D @duckcodeailabs/dql-cli
npx dql init .
npx dql semantic import dbt .
npm run notebook

Common Commands

The examples below use the short dql form. For a project-local installation, run them as npm exec -- dql ... or through a repository script. See the complete CLI reference for every command, subcommand, flag, and exit code.

• dql init [directory] — create a starter DQL project
• dql new block <name> — scaffold a new DQL block in the current project
• dql new semantic-block <name> — scaffold a semantic block plus companion YAML files
• dql new dashboard <name> — scaffold a new dashboard in dashboards/
• dql new workbook <name> — scaffold a new workbook in workbooks/
• dql doctor [path] — check local setup, config, and starter folders
• dql parse <file.dql> — parse and validate a DQL block
• dql fmt <file.dql> — format a DQL file
• dql validate [path] — validate DQL files and semantic references
• dql certify <file.dql> — run certification checks
• dql preview <file.dql> — preview a block in the browser
• dql build <file.dql> — build a static bundle in dist/
• dql serve [directory] — serve a built bundle locally

Learn More

• Root docs: ../../README.md
• Quickstart: ../../docs/01-quickstart.md
• CLI reference: ../../docs/reference/cli.md
• Project config: ../../docs/reference/file-formats.md