dct init

Bootstrap a dbt Charts project, plus its AI and editor integrations.

dct init [OPTIONS]
dct init [OPTIONS] COMMAND [ARGS]

Without a subcommand, dct init runs the interactive bootstrap wizard. With a subcommand, it targets a specific integration.

Subcommands

Command	Purpose
dct init skills	Install dbt Charts workflow skills to agent skill directories
dct init mcp	Wire dbt Charts into an AI assistant via MCP (Cursor, Claude Code, ChatGPT, etc.)
dct init ci	Scaffold a GitHub Actions workflow that validates your boards on every PR
dct init code	Install the dbt Charts extension into VS Code
dct init vscode	Alias for dct init code
dct init cursor	Install the dbt Charts extension into Cursor

Top-level options

Flag	Description
--project-dir PATH	Project directory. Overrides the wizard's default root selection.
--force, -f	Overwrite existing scaffold files.
--yes, -y	Accept all defaults without prompting.
--skills / --no-skills	Write dbt Charts workflow skills into this project's agent skill directories. Recommended in a git repository.
--mcp / --no-mcp	Set up MCP server for AI assistants.
--vscode / --no-vscode	Install dbt Charts extension into VS Code.
--cursor / --no-cursor	Install dbt Charts extension into Cursor.

Examples

# Interactive wizard
dct init

# Accept all defaults
dct init --yes

# Skip MCP setup
dct init --no-mcp

# Install workflow skills and MCP, no editor extensions
dct init --no-vscode --no-cursor

Project root resolution

dct init resolves its scaffold target in this order:

1. --project-dir or DCT_PROJECT_DIR
2. The detected dbt Charts or dbt project root, when dbt_charts.yml or dbt_project.yml exists at or above the current directory
3. Git root, when no dbt_charts.yml or dbt_project.yml exists above the current directory but a .git/ directory does
4. Current directory, when no project marker or git root is found

In the bare-git-repo case, the interactive wizard shows both paths and asks whether to scaffold at the git root instead of the current subdirectory. The default is the git root. dct init --yes takes that same default without prompting.

dct init skills

Install dbt Charts workflow skills for file-based agent auto-discovery. Writes CLI-rendered skill files, namespaced under a dct- prefix (dct-board-build/, dct-board-design/, ...), to .agents/skills/ (Cursor, Codex, Copilot) and/or the Claude Code skills directory. Without --project-dir, the install root is the git root enclosing the current directory (or the dbt Charts project root if there's no git repo), so monorepos with nested projects don't accumulate divergent skill copies. Pass --project-dir to install into that project instead; it must name a directory that holds a dbt Charts or dbt project, and errors with a suggestion otherwise rather than resolving upward. Pass --global to install into your user-level skill directories instead (Claude Code's, and ~/.agents/skills/ for Codex), so any new project on this machine picks up the skills without a per-repo install. On a machine with neither agent configured it writes nothing and exits 1; --dir PATH names an explicit destination. Does not configure MCP or modify AGENTS.md / CLAUDE.md.

The dct- prefix keeps our skills out of the way of any other skill your project or another tool installs under the same directory. Gitignore ours with a single glob (.agents/skills/dct-*/, or the same dct-*/ pattern under the Claude Code skills directory) without touching anyone else's. Every install always overwrites: re-run dct init skills after pip install -U dbt-charts to pick up new or updated skill bodies, and a skill the wheel no longer ships is removed on the next run.

dct init skills [OPTIONS] [TARGET]

Arguments

Argument	Description
TARGET	Install target: agents (Cursor/Codex/Copilot), codex, or claude. Omit to auto-detect.

Options

Flag	Description
--all	Install to every detected skill directory.
--dir PATH	Explicit destination directory.
--global	Install into your user-level skill directories (Claude Code's, and ~/.agents/skills for Codex) instead of a repository.
--check	Dry run: show what would be installed without writing files.
--project-dir PATH	Install into this project directory instead of walking up to the enclosing git root.

Examples

dct init skills                 # Detect targets and install
dct init skills agents          # .agents/skills/ only (Cursor, Codex, Copilot)
dct init skills claude          # Claude Code skills directory only
dct init skills --all           # Every detected target directory
dct init skills --dir PATH      # Explicit destination
dct init skills --global        # User-level: Claude Code's skills dir and/or ~/.agents/skills
dct init skills --check         # Dry run

dct init mcp

Add dbt Charts to your AI client's MCP configuration. Configures the MCP server only. Run dct init skills separately to install workflow skills to agent file directories.

dct init mcp [OPTIONS] [CLIENT]

Arguments

Argument	Description
CLIENT	One of: cursor, vscode, claude, claude-code, codex, copilot, or print. Omit to auto-detect installed clients.

Options

Flag	Description
--all	Write MCP config files for every supported client.
--force, -f	Overwrite existing dbt Charts config.
--project-dir PATH	Path to the dbt Charts or dbt project the MCP server should target. Embedded into the generated server entry.

Project root resolution

dct init mcp walks up from the current directory looking for dbt_charts.yml or dbt_project.yml. Pass --project-dir to override. When the project root diverges from the AI client's workspace (for example, a project nested under a larger repo), the generated server entry includes --project-dir <abs-path> so the server still starts in the right place.

Examples

dct init mcp                              # Auto-detect clients + project
dct init mcp cursor                       # Configure Cursor only
dct init mcp claude-code                  # Configure Claude Code
dct init mcp --all                        # Write every supported config file
dct init mcp --project-dir ./analytics    # Target a specific project dir
dct init mcp print                        # Print config JSON (for manual setup)

dct init ci

Scaffold a GitHub Actions workflow that runs dct validate on every pull request that touches your boards.

dct init ci [OPTIONS]

The workflow is written at the repository root (the only place GitHub reads workflows from) as .github/workflows/dbt-charts.yml for a project at the root, or .github/workflows/dbt-charts-<project-path>.yml for a nested project, so each project in a monorepo owns its own gate. It is safe to re-run: an existing file is never overwritten without --force. A directory that is not inside a dct/dbt project, or a project with no git repository above it, fails loudly instead of scaffolding a gate that could never fire.

Options

Option	Description
--force, -f	Overwrite an existing workflow file
--project-dir PATH	Target a specific project root instead of walking up from the current directory

Nested dbt roots

Your dbt project is often not at the repository root; a monorepo may hold several, nested in subdirectories. GitHub's paths: filters are always resolved relative to the repository root, so a hand-written charts/** filter silently never matches a nested project, and the gate looks green because it never ran.

dct init ci resolves the repository root and the project root separately and qualifies every path with the project's repo-relative path. For a project at analytics/transform_bi:

on:
  pull_request:
    paths:
      - 'analytics/transform_bi/charts/**'
      - 'analytics/transform_bi/dbt_charts.yml'

jobs:
  validate:
    defaults:
      run:
        working-directory: analytics/transform_bi

A project at the repository root omits working-directory entirely.

What it checks

The scaffolded workflow is structural: dct validate checks board YAML shape, enums, references, and unknown keys without running a single query, so the job needs no warehouse credentials and runs on any runner.

To also validate dbt ref() and source() calls against your models, add a parse step before the validate step:

      - name: Parse the dbt project
        run: |
          dbt deps
          dbt parse

That writes target/manifest.json, which dct validate reads to resolve refs, catching a renamed or deleted model without connecting to your warehouse (dbt parse needs a profiles.yml, but does not query). Without it, refs are reported as a WARN-DBT-MANIFEST-MISSING warning rather than checked.

The manifest also powers the model-column drift check: a board query reading a column a model's own SQL no longer produces fails validation with ERR-DBT-MODEL-COLUMN-MISSING, a rename caught before dbt run rebuilds the warehouse, still with no connection. The full CI ladder, tier by tier, is in Validating Boards in CI.

Examples

dct init ci                            # Scaffold for the detected project
dct init ci --project-dir ./analytics  # Target a specific dbt root
dct init ci --force                    # Overwrite the existing workflow

dct init code / dct init vscode

Install the dbt Charts extension into VS Code. Adds YAML schema, completion, and live-preview integration; see VS Code & Cursor Extension.

dct init code
dct init vscode    # alias

dct init cursor

Install the dbt Charts extension into Cursor.

dct init cursor

Related

• CLI and MCP for AI assistants: when to use the CLI vs MCP
• dct mcp serve: start the MCP server directly
• dct skills: view the packaged skills that get installed