About flags (global configs)

In dbt, "flags" (also called "global configs") are configurations for fine-tuning how dbt runs your project. They differ from resource-specific configs that tell dbt about 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.

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 via 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".

Setting flags

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

• Project-level flags in dbt_project.yml: Define version-controlled defaults for everyone running this project. Also, opt in or opt out of behavior changes to manage your migration off legacy functionality.
• Environment variables: Define different behavior in different runtime environments (development vs. production vs. continuous integration, or different behavior for different users in development (based on personal preferences).
• CLI options: Define behavior specific to this invocation. Supported for all dbt commands.

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

# set this environment variable to 'True' (bash syntax)
export DBT_FAIL_FAST=1
dbt run

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 (DBT_LOG_PATH, DBT_STATE). 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 }}'

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.

Available flags

Flag name	Type	Default	Supported in project?	Environment variable	Command line option	Supported in Cloud CLI?
cache_selected_only	boolean	False	✅	DBT_CACHE_SELECTED_ONLY	--cache-selected-only, --no-cache-selected-only	✅
debug	boolean	False	✅	DBT_DEBUG	--debug, --no-debug	✅
defer	boolean	False	❌	DBT_DEFER	--defer, --no-defer	✅ (enabled by default)
defer_state	path	None	❌	DBT_DEFER_STATE	--defer-state	❌
fail_fast	boolean	False	✅	DBT_FAIL_FAST	--fail-fast, -x, --no-fail-fast	✅
full_refresh	boolean	False	✅ (as resource config)	DBT_FULL_REFRESH	--full-refresh, --no-full-refresh	✅
indirect_selection	enum	eager	✅	DBT_INDIRECT_SELECTION	--indirect-selection	❌
introspect	boolean	True	❌	DBT_INTROSPECT	--introspect, --no-introspect	❌
log_cache_events	boolean	False	❌	DBT_LOG_CACHE_EVENTS	--log-cache-events, --no-log-cache-events	❌
log_format_file	enum	default (text)	✅	DBT_LOG_FORMAT_FILE	--log-format-file	❌
log_format	enum	default (text)	✅	DBT_LOG_FORMAT	--log-format	❌
log_level_file	enum	debug	✅	DBT_LOG_LEVEL_FILE	--log-level-file	❌
log_level	enum	info	✅	DBT_LOG_LEVEL	--log-level	❌
log_path	path	None (uses logs/)	❌	DBT_LOG_PATH	--log-path	❌
partial_parse	boolean	True	✅	DBT_PARTIAL_PARSE	--partial-parse, --no-partial-parse	✅
populate_cache	boolean	True	✅	DBT_POPULATE_CACHE	--populate-cache, --no-populate-cache	✅
print	boolean	True	❌	DBT_PRINT	--print	❌
printer_width	int	80	✅	DBT_PRINTER_WIDTH	--printer-width	❌
profile	string	None	✅ (as top-level key)	DBT_PROFILE	--profile	❌
profiles_dir	path	None (current dir, then HOME dir)	❌	DBT_PROFILES_DIR	--profiles-dir	❌
project_dir	path		❌	DBT_PROJECT_DIR	--project-dir	❌
quiet	boolean	False	❌	DBT_QUIET	--quiet	✅
resource-type (v1.8+)	string	None	❌	DBT_RESOURCE_TYPES DBT_EXCLUDE_RESOURCE_TYPES	--resource-type --exclude-resource-type	✅
send_anonymous_usage_stats	boolean	True	✅	DBT_SEND_ANONYMOUS_USAGE_STATS	--send-anonymous-usage-stats, --no-send-anonymous-usage-stats	❌
source_freshness_run_project_hooks	boolean	False	✅	❌	❌	❌
state	path	none	❌	DBT_STATE, DBT_DEFER_STATE	--state, --defer-state	❌
static_parser	boolean	True	✅	DBT_STATIC_PARSER	--static-parser, --no-static-parser	❌
store_failures	boolean	False	✅ (as resource config)	DBT_STORE_FAILURES	--store-failures, --no-store-failures	✅
target_path	path	None (uses target/)	❌	DBT_TARGET_PATH	--target-path	❌
target	string	None	❌	DBT_TARGET	--target	❌
use_colors_file	boolean	True	✅	DBT_USE_COLORS_FILE	--use-colors-file, --no-use-colors-file	❌
use_colors	boolean	True	✅	DBT_USE_COLORS	--use-colors, --no-use-colors	❌
use_experimental_parser	boolean	False	✅	DBT_USE_EXPERIMENTAL_PARSER	--use-experimental-parser, --no-use-experimental-parser	❌
version_check	boolean	varies	✅	DBT_VERSION_CHECK	--version-check, --no-version-check	❌
warn_error_options	dict		✅	DBT_WARN_ERROR_OPTIONS	--warn-error-options	✅
warn_error	boolean	False	✅	DBT_WARN_ERROR	--warn-error, --no-warn-error	✅
write_json	boolean	True	✅	DBT_WRITE_JSON	--write-json, --no-write-json	✅