CLI#

This page provides documentation for the dbt-bouncer CLI.

run#

The run subcommand executes dbt-bouncer checks against your dbt project:

dbt-bouncer run --config-file dbt-bouncer.yml

This is the primary command for running checks. For backwards compatibility, dbt-bouncer (without the run subcommand) still works and behaves identically.

All the main CLI options (--check, --only, --output-file, etc.) work with both dbt-bouncer run and the legacy dbt-bouncer invocation. The --dry-run option is only available via dbt-bouncer run --dry-run.

Options#

`--config-file`#

Type: Path Default: dbt-bouncer.yml Required: No Environment variable: DBT_BOUNCER_CONFIG_FILE (see Config file)

Specifies the location of the YAML configuration file containing your dbt-bouncer checks.

Example:

dbt-bouncer run --config-file config/checks.yml

`--dry-run`#

Type: Flag Default: False Required: No Environment variable: DBT_BOUNCER_DRY_RUN

When passed, assembles the full check list as normal but prints a summary table showing the check name, resource type, and count for each check that would run — then exits with code 0 without executing any checks. Useful for previewing which checks are in scope before a full run.

Example:

dbt-bouncer run --dry-run

Example output:

╭─ Dry run — checks that would execute ─────────────────────╮
│ Check name                     │ Resource type │ Count     │
│ CheckModelNamePattern          │ model         │  1234     │
│ CheckModelDescriptionPopulated │ model         │  1234     │
│ CheckSourceDescriptionPopulated│ source        │    56     │
╰────────────────────────────────────────────────────────────╯

Dry run complete. 2524 check(s) would run.

`--check`#

Type: String (comma-separated) Default: Empty (runs all checks) Required: No Environment variable: DBT_BOUNCER_CHECK

Limits the checks run to specific check names. Multiple checks can be specified as a comma-separated list.

Examples:

# Run a single check
dbt-bouncer run --check check_model_has_unique_test

# Run multiple checks
dbt-bouncer run --check check_model_names,check_source_freshness_populated

`--only`#

Type: String (comma-separated) Default: Empty (runs all categories) Required: No Environment variable: DBT_BOUNCER_ONLY

Limits the checks run to specific categories. Multiple categories can be specified as a comma-separated list.

Examples:

# Run only manifest checks
dbt-bouncer run --only manifest_checks

# Run catalog and manifest checks
dbt-bouncer run --only catalog_checks,manifest_checks

`--baseline`#

Type: Path Default: None Required: No Environment variable: DBT_BOUNCER_BASELINE

Path to a baseline file written by dbt-bouncer baseline. Failures listed in the baseline are suppressed, so the run fails only on newly introduced failures. See Baselines for the workflow.

Example:

dbt-bouncer run --baseline .dbt-bouncer-baseline.json

`--preset`#

Type: Choice Options: minimal, standard, strict Default: None Required: No Environment variable: DBT_BOUNCER_PRESET

Runs a bundled preset config instead of a config file. A preset is a ready-made ruleset, so you can run dbt-bouncer without writing a config file first. See Presets for what each preset contains.

An explicit --config-file takes precedence. If you pass both, the preset is ignored and a warning is logged.

Examples:

# Run the strict preset without a config file
dbt-bouncer run --preset strict

# Scaffold an editable copy instead of running it
dbt-bouncer init --preset strict

`--state`#

Type: Path Default: None Required: No Environment variable: DBT_BOUNCER_STATE

Compares the current run against a base set of dbt artifacts. Failures present in the base run are suppressed, so the run fails only on new failures. The value is a directory of dbt artifacts from a previous run (the target directory containing manifest.json).

This matches dbt's own --state flag, which also points at a directory of artifacts from a previous run.

--state runs the checks twice (once against the base artifacts, once against the current artifacts), so it parses the artifacts twice and takes about twice as long as a normal run.

Example:

# Compare against a directory of base artifacts
dbt-bouncer run --state ./base-target

`--output-file`#

Type: Path Default: None (no output file is written) Required: No Environment variable: DBT_BOUNCER_OUTPUT_FILE

Specifies the location where check metadata will be saved. If not provided, no structured output file is written.

Example:

dbt-bouncer run --output-file results/check-results.json

`--output-format`#

Type: Choice Options: csv, json, junit, sarif, tap Default: json Required: No Environment variable: DBT_BOUNCER_OUTPUT_FORMAT

Specifies the format for the output file. Requires --output-file to be set.

Examples:

# Output as JSON (default)
dbt-bouncer run --output-format json

# Output as JUnit XML for CI integration
dbt-bouncer run --output-format junit --output-file results.xml

# Output as SARIF for GitHub Code Scanning
dbt-bouncer run --output-format sarif --output-file results.sarif

Do not parse the console table

The console results table is for humans. It truncates check names to fit the terminal width. Do not parse this table in scripts.

For machine-readable output, set --output-file and select a structured --output-format. The supported formats are csv, json, junit, sarif, and tap. Parse the output file instead of the console table.

`--output-only-failures`#

Type: Flag Default: False Required: No Environment variable: DBT_BOUNCER_OUTPUT_ONLY_FAILURES

When passed, only failures will be included in the output file. Successful checks are omitted.

Example:

dbt-bouncer run --output-file results.json --output-only-failures

`--show-all-failures`#

Type: Flag Default: False Required: No Environment variable: DBT_BOUNCER_SHOW_ALL_FAILURES

When passed, all failures will be printed to the console, even if an output file is specified.

Example:

dbt-bouncer run --show-all-failures

`-v, --verbosity`#

Type: Counter Default: 0 Required: No Environment variable: DBT_BOUNCER_VERBOSITY

Controls the verbosity of logging output. Can be specified multiple times to increase verbosity.

Examples:

# Basic logging
dbt-bouncer run -v

# More verbose logging
dbt-bouncer run -vv

# Maximum verbosity
dbt-bouncer run -vvv

Environment variables#

Every run option can also be set with an environment variable. This is useful when dbt-bouncer is invoked by a wrapper that does not let you control the command line — pre-commit run, for instance, passes no arguments beyond the args: list committed in .pre-commit-config.yaml.

Option	Environment variable
`--baseline`	`DBT_BOUNCER_BASELINE`
`--check`	`DBT_BOUNCER_CHECK`
`--dry-run`	`DBT_BOUNCER_DRY_RUN`
`--only`	`DBT_BOUNCER_ONLY`
`--output-file`	`DBT_BOUNCER_OUTPUT_FILE`
`--output-format`	`DBT_BOUNCER_OUTPUT_FORMAT`
`--output-only-failures`	`DBT_BOUNCER_OUTPUT_ONLY_FAILURES`
`--show-all-failures`	`DBT_BOUNCER_SHOW_ALL_FAILURES`
`--state`	`DBT_BOUNCER_STATE`
`-v`, `--verbosity`	`DBT_BOUNCER_VERBOSITY`

A command-line argument always wins over the corresponding environment variable.

Flags accept the usual truthy and falsy strings (1/0, true/false, yes/no). DBT_BOUNCER_VERBOSITY takes the count as a number, so DBT_BOUNCER_VERBOSITY=2 is equivalent to -vv.

These variables apply to run and to the legacy no-subcommand invocation. They are not read by validate, list or explain.

--config-file is the exception to the table: it is read from DBT_BOUNCER_CONFIG_FILE, but with its own precedence rules, described under Config file.

Example — getting machine-readable output from the pre-commit hook, which accepts no arguments of your own:

DBT_BOUNCER_OUTPUT_FILE=results.json \
DBT_BOUNCER_OUTPUT_FORMAT=json \
DBT_BOUNCER_OUTPUT_ONLY_FAILURES=true \
DBT_BOUNCER_ONLY=manifest_checks \
  pre-commit run dbt-bouncer --all-files

validate#

The validate subcommand checks your configuration file for common issues:

dbt-bouncer validate --config-file dbt-bouncer.yml

It will report:

YAML syntax errors with line numbers
Missing required fields (like name in checks)
Incorrect configuration types (e.g., if a check category is not a list)
Everything dbt-bouncer run would reject: unknown keys, unknown check parameters, and mistyped parameter values — with a "Did you mean" suggestion for the closest valid name

Example output for a valid config:

Config file is valid!

Example output for issues:

Found 2 issue(s) in config file:
  Line 1: Check is missing required 'name' field
  Line 3: model_name_patern: Extra inputs are not permitted. Did you mean 'model_name_pattern'?

Options#

`--config-file`#

Type: Path Default: dbt-bouncer.yml Required: No

Specifies the location of the YAML configuration file to validate.

Example:

dbt-bouncer validate --config-file config/checks.yml

baseline#

A baseline is the set of failures a project already has. With a baseline, a run reports only failures that are not in the baseline, so a team can adopt strict checks and fail only on new problems.

Use the baseline subcommand to record the current failures:

dbt-bouncer baseline --output-file .dbt-bouncer-baseline.json

This runs every configured check and writes each failure to the baseline file. The default file name is .dbt-bouncer-baseline.json. Commit the file, then pass it to run:

dbt-bouncer run --baseline .dbt-bouncer-baseline.json

Now the run fails only on failures that are not in the baseline. To burn down the backlog, fix some failures and regenerate the baseline.

The --state option does the same thing without a stored file. It compares the current run against a base set of artifacts and suppresses failures present in the base run. See the --state option under run.

You can pass --baseline and --state together. A failure is suppressed when it is present in either the baseline file or the state base run.

Options#

The baseline subcommand takes --config-file, --check, --only, --output-file, and -v/--verbosity. They behave the same as for run.

init#

The init subcommand creates a dbt-bouncer.yml configuration file interactively:

dbt-bouncer init

It asks a series of questions and writes a starter configuration file based on your answers:

Where your dbt artifacts are located (default: target)
Whether to check that all models have descriptions
Whether to check that all models have a unique test
Whether to enforce naming conventions for staging models

If a dbt-bouncer.yml file already exists, you will be prompted before it is overwritten.

`--preset`#

Instead of the interactive questions, init --preset <name> writes a bundled preset to dbt-bouncer.yml non-interactively. The comments in the preset are kept, so you get an editable, documented starting point.

dbt-bouncer init --preset standard

See Presets for what each preset contains.

presets#

A preset is a ready-made ruleset that ships with dbt-bouncer. Use a preset to start without writing a config file, then tune it to your project.

There are three presets:

Preset	Checks	Use for
`minimal`	A small, high-signal set (model and source documentation, a unique test, source freshness).	A first run, or a large legacy project.
`standard`	A balanced set of documentation, testing, and source-hygiene checks.	A typical project.
`strict`	A demanding, opinionated set that also enforces naming, coverage thresholds, and snapshot rules.	Teams that want strong governance.

Every preset needs only manifest.json. The naming patterns in strict assume snake_case names, so adjust them to your standard.

There are two ways to use a preset:

Run it directly, no config file needed:

dbt-bouncer run --preset strict

Scaffold an editable copy and extend it:

dbt-bouncer init --preset strict

To add catalog checks (needs catalog.json) or run-results checks (needs run_results.json), scaffold a copy and add those categories yourself.

list#

The list subcommand lists all available dbt-bouncer checks, grouped by category:

dbt-bouncer list

Options#

`--output-format`#

Type: Choice Options: json, text Default: text Required: No

Controls the output format. Use json for machine-readable output.

Examples:

# List checks as human-readable text (default)
dbt-bouncer list

# List checks as JSON
dbt-bouncer list --output-format json

explain#

The explain subcommand describes one check: what it does, its configurable parameters, and example usage. It works offline and does not need dbt artifacts:

dbt-bouncer explain check_model_names

A check can be referenced by its name or by its rule code, so dbt-bouncer explain MO038 shows the same output. An unknown name or code exits with code 2 (CONFIG_ERROR) and prints the closest match.

Example output:

╭─ check_model_names (MO038) ─────────────────────────────────────╮
│ Models must have a name that matches the supplied regex.        │
│ ...                                                             │
╰────────────────────────────────────────────────────── manifest ─╯
Parameters
╭─────────────────────┬──────┬──────────┬─────────╮
│ Name                │ Type │ Required │ Default │
├─────────────────────┼──────┼──────────┼─────────┤
│ model_name_pattern  │ str  │   yes    │ -       │
╰─────────────────────┴──────┴──────────┴─────────╯
Documentation: https://godatadriven.github.io/dbt-bouncer/checks/manifest/models/naming/

Options#

`--custom-checks-dir`#

Type: Path Default: None Required: No

Directory containing custom checks. When passed, custom checks can be explained too.

`--output-format`#

Type: Choice Options: json, text Default: text Required: No

Controls the output format. Use json for machine-readable output.

Example:

dbt-bouncer explain check_model_names --output-format json

studio#

The studio subcommand prints the Terminal Studio dashboard. The dashboard shows every available check in one table, marks the checks your config activates, and prints the full details of a single check when the filters narrow the table to one row:

dbt-bouncer studio

The command renders once and exits. It does not need dbt artifacts. Pass --config-file to mark active checks, and pass --results-file to show error and warning counts from a previous run.

Example output:

╭──────────────────────────────────────────────────────────────────────╮
│ dbt-bouncer studio  vX.X.X | search: 'alias'  (1 checks, 1 active)    │
╰──────────────────────────────────────────────────────────────────────╯
                     Available & Configured Checks
╭───────────┬────────────────────┬──────────┬──────────┬───────────────╮
│ Rule Code │ Check Name         │ Category │  Active  │ Description   │
├───────────┼────────────────────┼──────────┼──────────┼───────────────┤
│ MO058     │ check_model_alias  │ manifest │ ✓ active │ Models must…  │
╰───────────┴────────────────────┴──────────┴──────────┴───────────────╯

Options#

`--category`, `-c`#

Type: Choice Options: catalog_checks, manifest_checks, run_results_checks Default: None Required: No

Shows only the checks in one category. An invalid category exits with code 2 (CONFIG_ERROR).

Example:

dbt-bouncer studio --category manifest_checks

`--config-file`#

Type: Path Default: None Required: No

Location of the config file (YML, YAML, or TOML). The dashboard reads it to mark which checks are active in your project. Without this option, no check is marked active.

Example:

dbt-bouncer studio --config-file dbt-bouncer.yml

`--custom-checks-dir`#

Type: Path Default: None Required: No

Directory that contains custom checks. When you pass it, the dashboard lists your custom checks alongside the built-in ones.

`--results-file`#

Type: Path Default: None Required: No

Path to a dbt-bouncer JSON output file, written by dbt-bouncer run --output-file results.json --output-format json. The dashboard adds the error and warning count for each check. This is not dbt's own run_results.json.

Example:

dbt-bouncer run --output-file results.json --output-format json
dbt-bouncer studio --results-file results.json

`--search`, `-s`#

Type: String Default: None Required: No

Shows only the checks whose name, rule code, or description contains the supplied text.

Example:

dbt-bouncer studio --search alias

mcp#

The mcp subcommand starts a Model Context Protocol server on the stdio transport:

dbt-bouncer mcp

This lets AI coding agents (Claude Code, Cursor, etc.) query and run dbt-bouncer. The server exposes four tools:

read_project_config: Read and validate the project's config file. The agent learns which conventions the project enforces before it generates dbt code.
list_checks: List all available checks, grouped by category.
explain_check: Explain one check by name or rule code: description, parameters, and example usage.
run_checks: Run the configured checks against the project's dbt artifacts. This requires at minimum a manifest.json (from dbt parse).

The command requires the optional mcp dependency:

pip install 'dbt-bouncer[mcp]'

Example client configuration (Claude Code, .mcp.json):

{
  "mcpServers": {
    "dbt-bouncer": {
      "command": "dbt-bouncer",
      "args": ["mcp"]
    }
  }
}

Exit codes#

dbt-bouncer returns distinct exit codes so that CI pipelines and scripts can tell a check failure apart from a setup problem:

0 (SUCCESS): All checks have succeeded.
1 (CHECK_ERRORS): At least one check has failed. Check the logs for more information.
2 (CONFIG_ERROR): The config file is missing, unreadable, or invalid (e.g. an invalid --only value).
3 (ARTIFACT_ERROR): A required dbt artifact (manifest.json, catalog.json, run_results.json) is missing or was generated with an unsupported dbt version.
4 (NO_CHECKS_RUN): No checks ran because the config matched no resources. Check the package_name, the config file, the dbt artifacts, and any --check or --only filters.

These codes apply to both dbt-bouncer run and dbt-bouncer validate (which only ever returns SUCCESS, CHECK_ERRORS, or CONFIG_ERROR — for validate, CHECK_ERRORS means lint issues were found in the config file, not that dbt checks failed).

CLI#

run#

Options#

--config-file#

--dry-run#

--check#

--only#

--baseline#

--preset#

--state#

--output-file#

--output-format#

--output-only-failures#

--show-all-failures#

-v, --verbosity#

Environment variables#

validate#

Options#

--config-file#

baseline#

Options#

init#

--preset#

presets#

list#

Options#

--output-format#

explain#

Options#

--custom-checks-dir#

--output-format#

studio#

Options#

--category, -c#

--config-file#

--custom-checks-dir#

--results-file#

--search, -s#

mcp#

Exit codes#

`--config-file`#

`--dry-run`#

`--check`#

`--only`#

`--baseline`#

`--preset`#

`--state`#

`--output-file`#

`--output-format`#

`--output-only-failures`#

`--show-all-failures`#

`-v, --verbosity`#

`--config-file`#

`--preset`#

`--output-format`#

`--custom-checks-dir`#

`--output-format`#

`--category`, `-c`#

`--config-file`#

`--custom-checks-dir`#

`--results-file`#

`--search`, `-s`#