Skip to content

dct migrate

Update board YAML to the current release. Use it after upgrading dbt charts when a dashboard reports that it uses older YAML syntax. The command recognizes syntax from the YAML shape; board YAML does not carry a version: field.

dct migrate [OPTIONS] [PATH]...

Arguments

Argument Description
PATH... Board YAML file or directory to migrate. Omit paths to scan the project root.

Options

Flag Description
--dry-run Report the files that would change without writing them.
--project-dir PATH Project root for resolving paths.

Preview and Apply a Migration

Start with a dry run, review the change in your working tree, then rerun without --dry-run to write it.

dct migrate --dry-run
dct migrate
git diff

For a targeted migration, pass a board file or a directory:

dct migrate charts/revenue.yml
dct migrate charts/

The command prints a summary of updated files, files that already use current syntax, and files that need manual repair. It exits with status 1 when any file cannot be migrated; files with independent, successful migrations are still written.

What Gets Rewritten

dbt charts keeps immutable schemas for supported YAML grammars and checks them from newest to oldest. It uses the newest grammar the document matches, then applies every safe, structural migration between that grammar and the current one. A file that already matches the current grammar is left unchanged—even if it was created with an older dbt charts release.

For example, the retired style.board: block is renamed to style.frame::

# Before
style:
  board:
    width: 1200

# After
style:
  frame:
    width: 1200

This recognition is not a claim about when you wrote the file. It only answers which supported grammar its current shape satisfies.

Manual Repair

dct migrate only performs declared, lossless structural changes. It stops for a file when a change would alter meaning, discard information, or conflict with an already-present destination key. The error names the path and migration that need attention. Make that repair yourself, then run dct validate to check the result.

dct migrate charts/revenue.yml
# Repair the path reported by the command.
dct validate charts/revenue.yml

The command does not make backups or offer rollback. Keep your dashboards in version control and use git diff to review the rewrite; use git revert if you need to undo a committed migration.