CLI#
This page provides documentation for the dbt-bouncer CLI.
dbt-bouncer#
Entrypoint for dbt-bouncer.
When invoked without a subcommand, runs checks for backwards compatibility. Use 'dbt-bouncer run' for the explicit command.
Raises: Exit: If the version flag is passed or an invalid output format is provided.
Usage:
Options:
--config-file PATH Location of the config file (YML, YAML, or
TOML). [default: dbt-bouncer.yml]
--check TEXT Limit the checks run to specific check
names, comma-separated. Examples:
'check_model_has_unique_test', 'check_model_
names,check_source_freshness_populated'.
--only TEXT Limit the checks run to specific categories,
comma-separated. Examples:
'manifest_checks',
'catalog_checks,manifest_checks'.
--output-file PATH Location of the file where check metadata
will be saved.
--output-format [csv|json|junit|sarif|tap]
Format for the output file or stdout when no
output file is specified. Choices: csv,
json, junit, sarif, tap. Defaults to json.
[default: json]
--output-only-failures / --no-output-only-failures
If passed then only failures will be
included in the output file. [default: no-
output-only-failures]
--show-all-failures / --no-show-all-failures
If passed then all failures will be printed
to the console. [default: no-show-all-
failures]
-v, --verbosity Verbosity. [default: 0]
--version Show version and exit.
--install-completion Install completion for the current shell.
--show-completion Show completion for the current shell, to
copy it or customize the installation.
-h, --help Show this message and exit.
init#
Create a dbt-bouncer.yml file interactively.
Asks questions to customize your initial configuration.
Raises: Abort: If the user declines to overwrite an existing config file.
Usage:
Options:
list#
List all available dbt-bouncer checks, grouped by category.
Raises: Exit: If an invalid output format is provided.
Usage:
Options:
--output-format TEXT Output format. Choices: text, json. Defaults to text.
[default: text]
-h, --help Show this message and exit.
run#
Run dbt-bouncer checks against your dbt project.
[bold]Examples:[/bold]
Run all checks with default config: [cyan]$ dbt-bouncer run[/cyan]
Run specific checks only: [cyan]$ dbt-bouncer run --check check_model_names,check_model_has_unique_test[/cyan]
Run manifest checks only with custom config: [cyan]$ dbt-bouncer run --only manifest_checks --config-file my-config.yml[/cyan]
Save results to JSON file: [cyan]$ dbt-bouncer run --output-file results.json --output-format json[/cyan]
Raises: Exit: If an invalid output format is provided or the checks fail.
Usage:
Options:
--config-file PATH Location of the config file (YML, YAML, or
TOML). [default: dbt-bouncer.yml]
--check TEXT Limit the checks run to specific check
names, comma-separated.
--dry-run / --no-dry-run Print which checks would run (name, resource
type, count) without executing them.
[default: no-dry-run]
--only TEXT Limit the checks run to specific categories,
comma-separated.
--output-file PATH Location of the file where check metadata
will be saved.
--output-format [csv|json|junit|sarif|tap]
Format for the output file or stdout when no
output file is specified. Choices: csv,
json, junit, sarif, tap. Defaults to json.
[default: json]
--output-only-failures / --no-output-only-failures
If passed then only failures will be
included in the output file. [default: no-
output-only-failures]
--show-all-failures / --no-show-all-failures
If passed then all failures will be printed
to the console. [default: no-show-all-
failures]
-v, --verbosity Verbosity. [default: 0]
-h, --help Show this message and exit.
validate#
Validate the dbt-bouncer configuration file.
Checks for YAML syntax errors and common configuration issues, reporting line numbers for any issues found.
Raises: Exit: If the config file is valid or if issues are found. RuntimeError: If the config file is not found.
Usage:
Options:
--config-file PATH Location of the config file (YML, YAML, or TOML).
[default: dbt-bouncer.yml]
-h, --help Show this message and exit.
Run command#
The run subcommand executes dbt-bouncer checks against your dbt project:
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.
Validate command#
The validate subcommand checks your configuration file for common issues:
It will report:
- YAML syntax errors with line numbers
- Missing required fields (like
namein checks) - Incorrect configuration types (e.g., if a check category is not a list)
Example output for a valid config:
Example output for issues:
Found 2 issue(s) in config file:
Line 1: Check is missing required 'name' field
Line 3: YAML syntax error: ...
CLI Options#
The following options are available for the run command (and the legacy dbt-bouncer invocation):
--config-file#
Type: Path
Default: dbt-bouncer.yml
Required: No
Specifies the location of the YAML configuration file containing your dbt-bouncer checks.
Example:
--dry-run#
Type: Flag Default: False Required: No
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:
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
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
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
--output-file#
Type: Path Default: None (outputs to stdout) Required: No
Specifies the location where check metadata will be saved. If not provided, results are written to stdout.
Example:
--output-format#
Type: Choice
Options: csv, json, junit, sarif, tap
Default: json
Required: No
Specifies the format for the output file or stdout when no output file is specified.
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
--output-only-failures#
Type: Flag Default: False Required: No
When passed, only failures will be included in the output file. Successful checks are omitted.
Example:
--show-all-failures#
Type: Flag Default: False Required: No
When passed, all failures will be printed to the console, even if an output file is specified.
Example:
-v, --verbosity#
Type: Counter Default: 0 Required: No
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
Exit codes#
dbt-bouncer returns the following exit codes:
-
0: All checks have succeeded. -
1:- At least one check has failed. Check the logs for more information.
- A fatal error occurred during check setup or check execution. Check the logs for more information.