Skip to main content

About flags (global configs)

In dbt, "flags" (also called "global configs" and often configured with environment variables) are settings for fine-tuning how dbt runs your project. They differ from resource-specific configs that tell dbt what to run.

Flags control things like the visual output of logs, whether to treat specific warning messages as errors, or whether to "fail fast" after encountering the first error. Flags are "global" configs because they are available for all dbt commands and they can be set in multiple places.

You can use flags with the dbt Fusion engine or dbt Core engine through the CLI during local development or in dbt platform.

There is a significant overlap between dbt's flags and dbt's command line options, but there are differences:

  • Certain flags can only be set in dbt_project.yml and cannot be overridden for specific invocations by using CLI options.
  • If a CLI option is supported by specific commands, rather than supported by all commands ("global"), it is generally not considered to be a "flag".

You can configure flags in dbt_project.yml, environment variables, and CLI options. For details, refer to environment variable configs.

Setting flags​

There are multiple ways of setting flags, which depend on the use case:

The most specific setting "wins." If you set the same flag in all three places, the CLI option will take precedence, followed by the environment variable, and finally, the value in dbt_project.yml. If you set the flag in none of those places, it will use the default value defined within dbt.

Most flags can be set in all three places:

# dbt_project.yml
flags:
  # set default for running this project -- anywhere, anytime, by anyone
  fail_fast: true
dbt run --fail-fast # set to True for this specific invocation
dbt run --no-fail-fast # set to False

There are two categories of exceptions:

  1. Flags setting file paths: Flags for file paths that are relevant to runtime execution (for example, --log-path or --state) cannot be set in dbt_project.yml. To override defaults, pass CLI options or set environment variables (). Flags that tell dbt where to find project resources (for example, model-paths) are set in dbt_project.yml, but as a top-level key, outside the flags dictionary; these configs are expected to be fully static and never vary based on the command or execution environment.
  2. Opt-in flags: Flags opting in or out of behavior changes can only be defined in dbt_project.yml. These are intended to be set in version control and migrated via pull/merge request. Their values should not diverge indefinitely across invocations, environments, or users.

Accessing flags​

Custom user-defined logic, written in Jinja, can check the values of flags using the flags context variable.

# dbt_project.yml

on-run-start:
  - '{{ log("I will stop at the first sign of trouble", info = true) if flags.FAIL_FAST }}'

Available flags​

Because the values of flags can differ across invocations, we strongly advise against using flags as an input to configurations or dependencies (ref + source) that dbt resolves during parsing.

Common flag examples​

Use the --target flag to specify which target (environment) to use when running dbt commands. For example:

dbt run --target dev
dbt run --target prod
dbt build --target staging

The --target flag allows you to run the same dbt project against different environments without modifying your configuration files. Define the target in your profiles.yml file. Learn more about connection profiles and targets.

Use this table to compare all available flags and how to configure them across interfaces:

  • dbt CLI: Indicates whether the flag is supported in the dbt platform-supported CLI.
  • Type / default: Shows the accepted value type and default.
  • In project: Indicates whether you can set the flag in dbt_project.yml.
  • Env var: Shows the corresponding environment variable name, when available. In general, v1.10 and earlier use the DBT_ prefix, while v1.11+ uses the DBT_ENGINE_ prefix.
  • CLI flags: Lists command-line options for setting the flag for a specific invocation.

Was this page helpful?

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.

0
Loading