Skip to content

CLI Reference (dbterd)

Run dbterd --help or dbterd -h to see the basic guideline for CLI Reference.

Sample Datasets

The project includes several sample datasets in the samples/ directory that you can use to test and explore the CLI commands:

  • samples/jaffle-shop/: A simple dbt artifacts with customers, orders, and payments models
  • samples/dbtresto/: A more complex artifacts with dimension and fact tables for analysis
  • samples/dbt-constraints/: Demonstrates using constraints for relationships
  • samples/facebookad/, samples/fivetranlog/, samples/shopify/: Additional sample artifacts

The examples below show how to use these sample datasets with dbterd commands.

dbterd -h Usage: dbterd [OPTIONS] COMMAND [ARGS]...

Tools for producing diagram-as-code.

Options:
--version Show the version and exit.
-h, --help Show this message and exit.

Commands:
debug Inspect the hidden magics.
run Generate ERD file from reading dbt artifact files,...
run-metadata Generate ERD file from reading Discovery API (dbt Cloud).

Specify one of these sub-commands and you can find more help from there.

dbterd run

Command to generate diagram-as-a-code file from dbt artifact files, optionally downloading from Administrative API (dbt Cloud).

Examples:

# Generate DBML ERD from jaffle-shop sample
dbterd run --artifacts-dir ./samples/jaffle-shop

# Generate Mermaid ERD from jaffle-shop sample
dbterd run --artifacts-dir ./samples/jaffle-shop --target mermaid

# Generate D2 ERD from dbtresto sample
dbterd run --artifacts-dir ./samples/dbtresto --target d2

# Generate GraphViz ERD without columns
dbterd run --artifacts-dir ./samples/dbtresto --target graphviz --omit-columns
# Generate artifacts first
dbt docs generate

# Generate ERD in your preferred format
dbterd run [-t dbml or -t mermaid]
Usage: dbterd run [OPTIONS]

Generate ERD file from reading dbt artifact files, optionally downloading
from Administrative API (dbt Cloud) before hands.

Options:
  -s, --select TEXT               Selecttion criteria
  -ns, --exclude TEXT             Exclusion criteria
  -t, --target TEXT               Target to the diagram-as-code platform
                                  [default: dbml]
  -rt, --resource-type TEXT       Specified dbt resource type(seed, model,
                                  source, snapshot),default:model, use
                                  examples, -rt model -rt source
  -a, --algo TEXT                 Specified algorithm in the way to detect
                                  diagram connectors  [default:
                                  test_relationship]
  -enf, --entity-name-format TEXT
                                  Specified the format of the entity node's
                                  name  [default: resource.package.model]
  --omit-entity-name-quotes       Flag to omit double quotes in the entity
                                  name. Currently only dbml is supported
  -o, --output TEXT               Output the result file. Default to the
                                  cwd/target
  -ofn, --output-file-name TEXT   Output the result file name. Default is
                                  defined in the target module
  --omit-columns                  Flag to omit columns in diagram. Currently
                                  only mermaid is supported
  -ad, --artifacts-dir TEXT       Specified the path to dbt artifact directory
                                  which known as /target directory
  -mv, --manifest-version TEXT    Specified dbt manifest.json version
  -cv, --catalog-version TEXT     Specified dbt catalog.json version
  --dbt                           Flag to indicate the Selection to follow
                                  dbt's one leveraging Programmatic Invocation
  -dpd, --dbt-project-dir TEXT    Specified dbt project directory path
  -dt, --dbt-target TEXT          Specified dbt target name
  --dbt-auto-artifacts            Flag to force generating dbt artifact files
                                  leveraging Programmatic Invocation
  --dbt-cloud                     Flag to download dbt artifact files using
                                  dbt Cloud API. This requires the additional
                                  parameters to be able to connection to dbt
                                  Cloud API
  --dbt-cloud-host-url TEXT       Configure dbt Cloud's Host URL. Try to get
                                  OS environment variable
                                  (DBTERD_DBT_CLOUD_HOST_URL) if not
                                  specified. Sample dbt Cloud Run URL: https:/
                                  /<HOST_URL>/deploy/<ACCOUNT_ID>/projects/irr
                                  elevant/runs/<RUN_ID>  [default:
                                  cloud.getdbt.com]
  --dbt-cloud-account-id TEXT     Configure dbt Cloud's Account ID. Try to get
                                  OS environment variable
                                  (DBTERD_DBT_CLOUD_ACCOUNT_ID) if not
                                  specified
  --dbt-cloud-run-id TEXT         Configure dbt Cloud's completed Run ID. Try
                                  to get OS environment variable
                                  (DBTERD_DBT_CLOUD_RUN_ID) if not specified
  --dbt-cloud-job-id TEXT         Configure dbt Cloud's Job ID. Try to get OS
                                  environment variable
                                  (DBTERD_DBT_CLOUD_JOB_ID) if not specified
  --dbt-cloud-service-token TEXT  Configure dbt Service Token (Permissions:
                                  Job Admin). Try to get OS environment
                                  variable (DBTERD_DBT_CLOUD_SERVICE_TOKEN) if
                                  not specified. Visit
                                  https://docs.getdbt.com/docs/dbt-cloud-
                                  apis/service-tokens to see how to generate
                                  it.
  --dbt-cloud-api-version TEXT    Configure dbt Cloud Administrative API
                                  version. Try to get OS environment variable
                                  (DBTERD_DBT_CLOUD_API_VERSION) if not
                                  specified.  [default: v2]
  -h, --help                      Show this message and exit.

dbterd run --select (-s)

Selection criteria.

Select all dbt models if not specified, supports multiple options

Rules:

  • By name: model name starts with input string
  • By exact: exact model name, formed as exact:model.package.name
  • By schema: schema name starts with an input string, formed as schema:<your_schema_name>
  • By wildcard: model name matches to a wildcard pattern, formed as wildcard:<your_wildcard>
  • By exposure: exposure name, exact match

Examples:

dbterd run -s "model.package.partital_name"

# Example with jaffle-shop sample
dbterd run --artifacts-dir ./samples/jaffle-shop -s "model.jaffle_shop.order"
dbterd run -s "exact:model.package.name"

# Example with jaffle-shop sample
dbterd run --artifacts-dir ./samples/jaffle-shop -s "exact:model.jaffle_shop.orders"
dbterd run -s "schema:my_schema_name"

# Example with dbtresto sample
dbterd run --artifacts-dir ./samples/dbtresto -s "schema:dbt_resto"
dbterd run -s "wildcard:*xyz"

# Example with dbtresto sample
dbterd run --artifacts-dir ./samples/dbtresto -s "wildcard:*fact_*"
dbterd run -s "exposure:my_exposure_name"

AND and OR logic

  • AND logic is applied to a single selection split by comma (,)
  • OR logic is applied to 2+ selection

Examples:

# All models belong to 'abc' schema AND also need to match the pattern of '*xyz.*'
dbterd run -s schema:abc,wildcard:*xyz.*
# All models belong to 'abc' schema, OR match to the pattern of '*xyz.*'
dbterd run -s schema:abc -s wildcard:*xyz.*

dbterd run --exclude (-ns)

Exclusion criteria. Rules are the same as Selection Criteria.

Do not exclude any dbt models if not specified, supports multiple options

Examples:

dbterd run -ns 'model.package_name.table'
dbterd run --exclude 'model.package_name.table'

dbterd run --artifacts-dir (-ad)

Configure the path to directory containing dbt artifact files.

It will take the the nested /target directory of --dbt-project-dir if not specified.

Default to the current directory's /target if both this option and --dbt-project-dir option are not specified

Examples:

dbterd run -ad "./target"
dbterd run --artifacts-dir "./target"

dbterd run --output (-o)

Configure the path to directory containing the output diagram file.

Default to ./target

Examples:

dbterd run -o "./target"
dbterd run --output "./target"

dbterd run --output-file-name (-ofn)

Configure the output file name

Default to output.{modulename} which is defined in the target module

Examples:

dbterd run -ofn "erd.dbml"
dbterd run --output-file-name "erd.dbml"

dbterd run --target (-t)

Default to dbml

Supported target, please visit Generate the Targets

Examples:

dbterd run -t dbml
dbterd run -t mermaid
dbterd run -t d2
dbterd run -t graphviz
dbterd run -t plantuml
dbterd run -t drawdb
# Generate DBML output for jaffle-shop
dbterd run --artifacts-dir ./samples/jaffle-shop -t dbml

# Generate Mermaid ERD for dbtresto
dbterd run --artifacts-dir ./samples/dbtresto -t mermaid

# Generate D2 diagram for dbtresto
dbterd run --artifacts-dir ./samples/dbtresto -t d2

# Generate GraphViz output for jaffle-shop
dbterd run --artifacts-dir ./samples/jaffle-shop -t graphviz
dbterd run --target dbml

dbterd run --algo (-a)

Specified algorithm in the way to detect diagram connectors

Check the docs 📖

Supported ones:

  • test_relationship: Looking for all relationship tests to understand the ERs
  • semantic: Looking for all semantic models' entities (primary & foreign) to understand the ERs

In the advanced use case of test_relationship, the test name can be configurable by following syntax:

{algorithm_name}:(name:{contains_test_name}|c_from:{referencing_column_name}|c_to:{referenced_column_name})

In the above:

  • algorithm_name (Mandatory): test_relationship or semantic
  • contains_test_name: Configure the test name (detected with contains logic). Default to relationship
  • c_from: Configure the test metadata attribute (1) for the foreign key column name(s). If (1)'s value is multiple columns, it will concat them all with _and wording > NOTE: It always looking at the column_name attribute firstly
  • c_to: Configure the test metadata attribute (2) for the referenced column name(s). If (2)'s value is multiple columns, it will concat them all with _and wording. Default to field

For example, if you would use dbt-constraints package

The dbt-constraints package is using different name of test which is close to the constraint names, in this case, you would need to customize the input string here:

dbterd run \
--algo "test_relationship:(name:foreign_key|c_from:fk_column_name|c_to:pk_column_name)"

Examples:

dbterd run -a test_relationship

# Example with jaffle-shop sample (using test_relationship algorithm)
dbterd run --artifacts-dir ./samples/jaffle-shop -a test_relationship -t mermaid
dbterd run -a semantic

# Example with dbtresto sample (using semantic algorithm)
dbterd run --artifacts-dir ./samples/dbtresto -a semantic -t d2
dbterd run --algo test_relationship
dbterd run --algo "test_relationship:(name:foreign_key|c_from:fk_column_name|c_to:pk_column_name)"

# Example with dbt-constraints sample (using foreign_key test)
dbterd run --artifacts-dir ./samples/dbt-constraints -a "test_relationship:(name:foreign_key)" -t mermaid

dbterd run --omit-columns

Flag to omit columns in diagram. Currently only mermaid is supported

Default to False

Examples:

dbterd run --target mermaid --omit-columns

# Example with dbtresto sample (omitting columns for a cleaner diagram)
dbterd run --artifacts-dir ./samples/dbtresto --target mermaid --omit-columns

dbterd run --manifest-version (-mv)

Specified dbt manifest.json version

Auto detect if not specified

Examples:

dbterd run --manifest-version 7
dbterd run -mv 7

dbterd run --catalog-version (-cv)

Specified dbt catalog.json version

Auto detect if not specified

Examples:

dbterd run --catalog-version 7
dbterd run -cv 7

dbterd run --resource-type (-rt)

Specified dbt resource type(seed, model, source, snapshot).

Default to ["model"], supports multiple options

Examples:

dbterd run -rt model -rt source
dbterd run --resource-type model

dbterd run --dbt

Flag to indicate the Selection to follow dbt's one leveraging Programmatic Invocation

Default to False

Examples:

dbterd run -s +something --dbt
# select 'something' and the upstream
dbterd run -s something
# select starts with 'something'

dbterd run --dbt --dbt-auto-artifact

Flag to indicate force running dbt docs generate to the targeted project in order to produce the dbt artifact files.

This option have to be enabled together with --dbt option, and will override the value of --artifacts-dir to be using the /target dir of the value of --dbt-project-dir.

Default to False

Examples:

dbterd run -s +something --dbt --dbt-auto-artifacts

dbterd run --dbt-project-dir (-dpd)

Specified dbt project directory path

You should specified this option if your CWD is not the dbt project dir, and normally used with --dbt enabled. It will take the value of --artifacts-dir if not specified.

Default to the current directory if both this option and --artifacts-dir option are not specified

Examples:

dbterd run -s +something --dbt-project-dir /path/to/dbt/project --dbt
# select 'something' and the upstream of the dbt project located at /path/to/dbt/project
# the artifacts dir will probably be assumed as: /path/to/dbt/project/target

dbterd run --dbt-target (-dt)

Specified dbt target name

Probably used with --dbt enabled.

Default to the dbt's profile configuration

Examples:

dbterd run -s +something --dbt-project-dir /path/to/dbt/project --dbt --dbt-target prod
# select 'something' and the upstream of the dbt project located at /path/to/dbt/project using target name 'prod'
# the artifacts dir will probably be assumed as: /path/to/dbt/project/target

dbterd run --entity-name-format (-enf)

Decide how the table name is generated on the ERD.

By default, the table name is the dbt node name (resource_type.package_name.model_name).

Currently, it supports the following keys in the format:

  • resource.package.model (by default)
  • database.schema.table
  • Or any other partial forms e.g. schema.table, resource.model

Examples:

dbterd run --entity-name-format resource.package.model # by default
dbterd run --entity-name-format database.schema.table # with fqn of the physical tables
dbterd run --entity-name-format schema.table # with schema.table only
dbterd run --entity-name-format table # with table name only
# Generate ERD with simplified entity names from jaffle-shop sample
dbterd run --artifacts-dir ./samples/jaffle-shop --entity-name-format schema.table -t mermaid

# Generate ERD with table names only from dbtresto sample
dbterd run --artifacts-dir ./samples/dbtresto --entity-name-format table -t d2

dbterd run --omit-entity-name-quotes

Flag to omit the double quotes in the generated entity name. Currently only dbml is supported.

Default to False

Enabled it to allow dbdocs to recognize the schemas and display them as grouping:

  • With quotes:

dbdocs-enf-with-quotes

  • Without quotes:

dbdocs-enf-without-quotes

⚠️ As of 2024 June: DBML doesn't support nested schema in the entity name which means 'database.schema.table' won't be allowed, but 'schema.table' does!

Examples:

dbterd run --entity-name-format resource.package.model --omit-entity-name-quotes # ❌
dbterd run --entity-name-format database.schema.table --omit-entity-name-quotes # ❌
dbterd run --entity-name-format schema.table --omit-entity-name-quotes # ✅

dbterd run --dbt-cloud

Decide to download artifact files from dbt Cloud Job Run instead of compiling locally.

Check Download artifacts from a Job Run for more details.

Examples:

dbterd run --dbt-cloud
dbterd run --dbt-cloud --select wildcard:*transaction*

dbterd run-metadata

Command to generate diagram-as-a-code file by connecting to dbt Cloud Discovery API using GraphQL connection.

Check this guideline for more details.

Examples:

# Generate DBML ERD from dbt Cloud environment
dbterd run-metadata --dbt-cloud-environment-id 123456 --dbt-cloud-service-token your_token

# Generate Mermaid ERD from dbt Cloud with specific models
dbterd run-metadata --target mermaid --select model.project.customers --dbt-cloud-environment-id 123456

# Generate D2 ERD with custom query file
dbterd run-metadata --target d2 --dbt-cloud-environment-id 123456 --dbt-cloud-query-file-path ./my_query.gql
dbterd run-metadata [-t dbml or -t mermaid]
Usage: dbterd run-metadata [OPTIONS]

Generate ERD file from reading Discovery API (dbt Cloud).

Options:
  -s, --select TEXT               Selecttion criteria
  -ns, --exclude TEXT             Exclusion criteria
  -t, --target TEXT               Target to the diagram-as-code platform
                                  [default: dbml]
  -rt, --resource-type TEXT       Specified dbt resource type(seed, model,
                                  source, snapshot),default:model, use
                                  examples, -rt model -rt source
  -a, --algo TEXT                 Specified algorithm in the way to detect
                                  diagram connectors  [default:
                                  test_relationship]
  -enf, --entity-name-format TEXT
                                  Specified the format of the entity node's
                                  name  [default: resource.package.model]
  --omit-entity-name-quotes       Flag to omit double quotes in the entity
                                  name. Currently only dbml is supported
  -o, --output TEXT               Output the result file. Default to the
                                  cwd/target
  -ofn, --output-file-name TEXT   Output the result file name. Default is
                                  defined in the target module
  --omit-columns                  Flag to omit columns in diagram. Currently
                                  only mermaid is supported
  --dbt-cloud-host-url TEXT       Configure dbt Cloud's Host URL. Try to get
                                  OS environment variable
                                  (DBTERD_DBT_CLOUD_HOST_URL) if not
                                  specified. Sample dbt Cloud Run URL: https:/
                                  /<HOST_URL>/deploy/<ACCOUNT_ID>/projects/irr
                                  elevant/runs/<RUN_ID>  [default:
                                  cloud.getdbt.com]
  --dbt-cloud-service-token TEXT  Configure dbt Service Token (Permissions:
                                  Job Admin). Try to get OS environment
                                  variable (DBTERD_DBT_CLOUD_SERVICE_TOKEN) if
                                  not specified. Visit
                                  https://docs.getdbt.com/docs/dbt-cloud-
                                  apis/service-tokens to see how to generate
                                  it.
  --dbt-cloud-environment-id TEXT
                                  Configure dbt Cloud Environment ID - Used
                                  for Metadata (Discovery) API. Try to get OS
                                  environment variable
                                  (DBTERD_DBT_CLOUD_ENVIRONMENT_ID) if not
                                  specified.
  --dbt-cloud-query-file-path TEXT
                                  Configure dbt Cloud GraphQL query file path
                                  - Used for Metadata (Discovery) API. Try to
                                  get OS environment variable
                                  (DBTERD_DBT_CLOUD_QUERY_FILE_PATH) if not
                                  specified.
  -h, --help                      Show this message and exit.

dbterd debug

Shows hidden configured values, which will help us to see what configs are passed into and how they are evaluated to be used.

Examples:

# Show debug information for a run command
dbterd debug --artifacts-dir ./samples/jaffle-shop

# Show debug information for a run-metadata command
dbterd debug --dbt-cloud-environment-id 123456
2023-09-08 16:43:45,066 - dbterd - INFO - Run with dbterd==1.0.0 (main.py:54)
2023-09-08 16:43:45,071 - dbterd - INFO - **Arguments used** (main.py:63)
2023-09-08 16:43:45,073 - dbterd - DEBUG - {
    "artifacts_dir": "",
    "output": "C:\\Users\\DAT\\Documents\\Sources\\dbterd\\target",
    "select": [],
    "exclude": [],
    "target": "dbml",
    "algo": "test_relationship",
    "manifest_version": null,
    "catalog_version": null,
    "resource_type": [
        "model"
    ],
    "dbt": false,
    "dbt_project_dir": "",
    "dbt_target": null
} (main.py:64)
2023-09-08 16:43:45,079 - dbterd - INFO - **Arguments evaluated** (main.py:65)
2023-09-08 16:43:45,081 - dbterd - INFO - Using dbt artifact dir at: C:\Users\DAT\Documents\Sources\dbterd\target (base.py:41)
2023-09-08 16:43:45,082 - dbterd - INFO - Using dbt project  dir at: C:\Users\DAT\Documents\Sources\dbterd (base.py:42)
2023-09-08 16:43:45,084 - dbterd - DEBUG - {
    "artifacts_dir": "C:\\Users\\DAT\\Documents\\Sources\\dbterd\\target",
    "output": "C:\\Users\\DAT\\Documents\\Sources\\dbterd\\target",
    "select": [],
    "exclude": [],
    "target": "dbml",
    "algo": "test_relationship",
    "manifest_version": null,
    "catalog_version": null,
    "resource_type": [
        "model"
    ],
    "dbt": false,
    "dbt_project_dir": "C:\\Users\\DAT\\Documents\\Sources\\dbterd",
    "dbt_target": null
} (main.py:66)
Usage: dbterd debug [OPTIONS]

Inspect the hidden magics.

Options:
  -s, --select TEXT               Selecttion criteria
  -ns, --exclude TEXT             Exclusion criteria
  -t, --target TEXT               Target to the diagram-as-code platform
                                  [default: dbml]
  -rt, --resource-type TEXT       Specified dbt resource type(seed, model,
                                  source, snapshot),default:model, use
                                  examples, -rt model -rt source
  -a, --algo TEXT                 Specified algorithm in the way to detect
                                  diagram connectors  [default:
                                  test_relationship]
  -enf, --entity-name-format TEXT
                                  Specified the format of the entity node's
                                  name  [default: resource.package.model]
  --omit-entity-name-quotes       Flag to omit double quotes in the entity
                                  name. Currently only dbml is supported
  -o, --output TEXT               Output the result file. Default to the
                                  cwd/target
  -ofn, --output-file-name TEXT   Output the result file name. Default is
                                  defined in the target module
  --omit-columns                  Flag to omit columns in diagram. Currently
                                  only mermaid is supported
  -ad, --artifacts-dir TEXT       Specified the path to dbt artifact directory
                                  which known as /target directory
  -mv, --manifest-version TEXT    Specified dbt manifest.json version
  -cv, --catalog-version TEXT     Specified dbt catalog.json version
  --dbt                           Flag to indicate the Selection to follow
                                  dbt's one leveraging Programmatic Invocation
  -dpd, --dbt-project-dir TEXT    Specified dbt project directory path
  -dt, --dbt-target TEXT          Specified dbt target name
  --dbt-auto-artifacts            Flag to force generating dbt artifact files
                                  leveraging Programmatic Invocation
  --dbt-cloud                     Flag to download dbt artifact files using
                                  dbt Cloud API. This requires the additional
                                  parameters to be able to connection to dbt
                                  Cloud API
  --dbt-cloud-host-url TEXT       Configure dbt Cloud's Host URL. Try to get
                                  OS environment variable
                                  (DBTERD_DBT_CLOUD_HOST_URL) if not
                                  specified. Sample dbt Cloud Run URL: https:/
                                  /<HOST_URL>/deploy/<ACCOUNT_ID>/projects/irr
                                  elevant/runs/<RUN_ID>  [default:
                                  cloud.getdbt.com]
  --dbt-cloud-account-id TEXT     Configure dbt Cloud's Account ID. Try to get
                                  OS environment variable
                                  (DBTERD_DBT_CLOUD_ACCOUNT_ID) if not
                                  specified
  --dbt-cloud-run-id TEXT         Configure dbt Cloud's completed Run ID. Try
                                  to get OS environment variable
                                  (DBTERD_DBT_CLOUD_RUN_ID) if not specified
  --dbt-cloud-job-id TEXT         Configure dbt Cloud's Job ID. Try to get OS
                                  environment variable
                                  (DBTERD_DBT_CLOUD_JOB_ID) if not specified
  --dbt-cloud-service-token TEXT  Configure dbt Service Token (Permissions:
                                  Job Admin). Try to get OS environment
                                  variable (DBTERD_DBT_CLOUD_SERVICE_TOKEN) if
                                  not specified. Visit
                                  https://docs.getdbt.com/docs/dbt-cloud-
                                  apis/service-tokens to see how to generate
                                  it.
  --dbt-cloud-api-version TEXT    Configure dbt Cloud Administrative API
                                  version. Try to get OS environment variable
                                  (DBTERD_DBT_CLOUD_API_VERSION) if not
                                  specified.  [default: v2]
  --dbt-cloud-environment-id TEXT
                                  Configure dbt Cloud Environment ID - Used
                                  for Metadata (Discovery) API. Try to get OS
                                  environment variable
                                  (DBTERD_DBT_CLOUD_ENVIRONMENT_ID) if not
                                  specified.
  --dbt-cloud-query-file-path TEXT
                                  Configure dbt Cloud GraphQL query file path
                                  - Used for Metadata (Discovery) API. Try to
                                  get OS environment variable
                                  (DBTERD_DBT_CLOUD_QUERY_FILE_PATH) if not
                                  specified.
  -h, --help                      Show this message and exit.