Skip to content

CLI Reference

The dct command-line interface is the primary surface for working with dbt Charts. Every dashboard operation (validating board YAML, browsing your warehouse, rendering charts, running the local server, configuring AI assistants) runs through dct.

This section documents every command, its flags, and the typical workflows that combine them.

Getting help

dct --help               # Top-level command list
dct <command> --help     # Per-command flags and examples
dct --version            # Print version + install path

If output looks stale or unexpected, dct --version is the first thing to check. If dct can't reach your data, run dct doctor.

Command catalog

Authoring & validation

Command Purpose
validate Fast YAML schema + cross-reference validation, no DB, no execute
migrate Rewrite supported older YAML syntax to the current grammar
describe Describe a dashboard's queries / charts / variables

Data discovery

Command Purpose
search Search dashboards by keyword with ranked results
impact Which boards reference a column; the rename blast-radius lookup

Query inspection

Command Purpose
query Execute a named board query or raw SQL; add --validate to lint, --describe for column schema

Rendering & serving

Command Purpose
render Render a board to SVG, HTML, PNG, PDF, JSON, YAML, or terminal
serve Start the local dbt Charts server with live board routes
playground Interactive playground with YAML editor and live preview

Project setup & scaffolding

Command Purpose
init Bootstrap a dbt Charts project, plus AI / editor integrations
docs Browse dbt Charts YAML reference docs offline, or look up a render-warning code
skills List packaged agent skills or show one by name
doctor Diagnose why dct can't reach your data: install method, project, profiles.yml, per-source adapters

AI integration

Command Purpose
CLI and MCP for AI assistants When to use the CLI vs MCP for AI assistants
mcp MCP (Model Context Protocol) server commands for AI assistant integration

Cloud

Command Purpose
cloud Connect a project, wire up a warehouse, and render — dbt Charts Cloud from the terminal

Common options

Most commands accept the same project-resolution and output-formatting flags.

--project-dir PATH

Project root for resolving relative paths. If not provided, dct walks up from the current directory looking for dbt_charts.yml or dbt_project.yml.

dct validate --project-dir /path/to/dbt/project
dct query warehouse "SELECT 1" --project-dir /path/to/project

Use this when:

  • Running dct from outside the project directory
  • Working with multiple projects from one shell
  • CI/CD pipelines where project path varies

Can also be set via the DCT_PROJECT_DIR environment variable; the flag wins when both are set.

export DCT_PROJECT_DIR=/path/to/project
dct validate                           # equivalent to --project-dir /path/to/project
dct render charts/sales.yaml --project-dir /other/project  # flag wins

--dbt-project-dir PATH

Links an external dbt project, one that does not sit next to dbt_charts.yml (a separate repo, or a sibling directory in a monorepo). dct is entirely read-only with respect to dbt: it never invokes the dbt CLI, only reads dbt_project.yml, profiles.yml, and target/manifest.json off the linked directory for ref()/source() resolution and dbt-profile-based warehouse connections.

dct render charts/sales.yaml --project-dir . --dbt-project-dir ../my_dbt_project

Resolution order (first match wins):

  1. --dbt-project-dir flag
  2. DBT_PROJECT_DIR environment variable (dbt-core's own variable name, so a shell already configured for the dbt CLI needs no extra setup)
  3. dbt_project_dir: key in dbt_charts.yml, resolved relative to that file's directory
  4. The dct project root itself (today's sibling default: dbt_project.yml next to dbt_charts.yml)
# dbt_charts.yml
dbt_project_dir: ../my_dbt_project

--json

Most read-shaped commands (search, describe, docs, skills, query, validate) support --json for stable, agent-consumable output.

dct query mydb "SELECT table_name FROM INFORMATION_SCHEMA.TABLES" --json | jq '.rows'
dct validate charts/sales.yaml --json

The JSON shape is contract-stable; pipe into jq for any cross-cutting query the curated verbs don't anticipate.

--var KEY=VALUE

For commands that compile or execute a board (render, query, sometimes serve), variable values can be supplied repeatedly:

dct render charts/sales.yaml --var region=West --var category=Electronics
dct query charts/sales.yaml revenue --var region=West

Exit codes

All commands follow standard Unix exit codes:

  • 0: success
  • 1: error (validation failed, compilation error, file not found, etc.)
  • 2: bad CLI arguments (Typer / Click convention)

Suitable for use in scripts and CI/CD pipelines:

#!/bin/bash
if dct validate charts/ --strict; then
  echo "All dashboards valid"
else
  echo "Validation failed"
  exit 1
fi

Environment variables

dbt Charts respects dbt environment variables:

Variable Purpose
DBT_PROFILES_DIR Custom profiles directory (default: ~/.dbt)
DBT_TARGET Default target for dct serve
DBT_PROJECT_DIR Links an external dbt project directory for all commands that accept --dbt-project-dir (overridden by the flag); see --dbt-project-dir above

dbt Charts-specific variables:

Variable Purpose
DCT_PROJECT_DIR Default project directory for all commands that accept --project-dir (overridden by the flag)
DCT_PORT Default port for dct serve (overridden by --port)
DCT_DEFAULT_THEME Runtime override for the dct serve default theme; all boards without an explicit theme: inherit the resolved value. Resolution at startup: env var > the project's dbt_charts.yml top-level theme: key > shipped default (clarity). Set at serve startup; restarts are required to pick up changes. Examples: neon (dark), paper (warm), vivid. To pin a project's default theme in source control, set theme: <name> in dbt_charts.yml.
DCT_MAX_WORKERS Default --max-workers for dct render and dct serve (max parallel query workers; default 8 from config). Overridden by the flag. No effect on DuckDB, which serializes access regardless.
DCT_CACHE_PATH Default --cache path for dct render, dct serve, and dct mcp serve; persists the query-result cache to a DuckDB file instead of discarding it in-memory on exit. Overridden by the flag; mutually exclusive with --no-cache.
DCT_HTML_POLICY_CEILING Deployment ceiling for html_policy (none, safe-subset, trusted-raw); a board or project config requesting a higher tier is downgraded to this value. Default: unset (falls through to markdown.html_policy_ceiling in config, default trusted-raw). dbt Charts Cloud hard-pins this to safe-subset.
DCT_MAX_ROWS_CEILING Deployment ceiling for query result row count; a project's own execution.max_rows can only lower the effective limit, never raise it above this. Exceeding it truncates the result with a warning, not a hard error. Default: unset (no ceiling; config default 1,000,000).
DCT_MAX_RESULT_BYTES_CEILING Deployment ceiling for a single query result's serialized byte size; a project's own execution.max_result_bytes can only lower it. Exceeding it truncates the result with a warning, not a hard error. Default: unset (no ceiling; config default 50MB). dbt Charts Cloud hard-pins this to 10MB.
DCT_FILE_SOURCE_MAX_TABLES_CEILING Deployment ceiling for the number of table entries a file source's files: map may declare; a project's own execution.file_source_max_tables can only lower it. Exceeding it is a hard error. Default: unset (no ceiling; config default 500).
DCT_FILE_SOURCE_MAX_BYTES_CEILING Deployment ceiling for a file-source relation's uncompressed byte size; a project's own execution.file_source_max_bytes can only lower it. Exceeding it is a hard error. Default: unset (no ceiling; config default 5GB). dbt Charts Cloud hard-pins this to 50MB.
DCT_MAX_TEMPLATE_OUTPUT_BYTES_CEILING Deployment ceiling for one board render's cumulative Jinja-emitted template output; a project's own execution.max_template_output_bytes can only lower it. Exceeding it is a hard error, never a truncation. Default: unset (no ceiling; config default 50MB). dbt Charts Cloud hard-pins this to 10MB.

Workflow examples

Author → check → preview

# 1. Edit a board
vim charts/sales.yaml

# 2. Fast structural validation (no DB hit)
dct validate charts/sales.yaml

# 3. Full validation including warehouse references
dct render charts/sales.yaml --format json

# 4. Inspect a single query
dct query charts/sales.yaml revenue --limit 10

# 5. Render to terminal for quick check
dct render charts/sales.yaml --format terminal

# 6. Serve interactively
dct serve

Explore an unfamiliar warehouse

# 1. What schemas and tables exist?
dct query analytics "SELECT table_schema, table_name FROM INFORMATION_SCHEMA.TABLES"

# 2. What columns does a table have?
dct query analytics "SELECT column_name, data_type FROM INFORMATION_SCHEMA.COLUMNS WHERE table_name = 'orders'"

# 3. Find every column that looks like a timestamp
dct query analytics "SELECT table_name, column_name FROM INFORMATION_SCHEMA.COLUMNS WHERE column_name LIKE '%\_at' ESCAPE '\'"

# 4. Search dashboards that already use it
dct search "orders"

CI pipeline

# Validate all dashboards before deployment
dct validate charts/ --strict

# Render dashboards as deployable artifacts
for board in charts/*.yml; do
  dct render "$board" --format html --output "dist/$(basename "$board" .yml).html"
done

Wire up an AI assistant

# CLI-first: install skills to agent directories (see ai-cli-and-mcp.md)
dct init skills              # .agents/skills/ for Cursor/Codex + Claude Code skills dir

# Optional: also configure MCP for MCP-aware clients
dct init mcp                 # auto-detect Cursor, VS Code, Claude Code, Codex, …
dct init ci                  # GitHub Actions workflow validating boards on PRs

# Or run the MCP server directly for any MCP-aware client
dct mcp serve