CLI Commands & Interface
Relevant source files
The following files were used as context for generating this wiki page:
The dbt-core CLI provides a robust command-line interface for data analysts and engineers to build, test, and manage analytics code. Rebuilt in Rust for the Fusion engine, the interface is designed for high performance and strict language enforcement while maintaining compatibility with standard dbt workflows. Sources: crates/dbt-clap-core/src/lib.rs:74-78, README.md:14-20
CLI Architecture & Parsing
The CLI architecture is built upon the clap crate, using a structured approach to separate user-facing arguments from internal execution logic. The primary entry point is the CliParser, which produces a Cli struct containing a Command (the subcommand to run) and CommonArgs (global flags). Sources: crates/dbt-clap-core/src/lib.rs:104-110, crates/dbt-clap-core/src/lib.rs:252-255
Parsing Workflow
The transformation of raw string arguments into actionable execution parameters follows a specific pipeline:
- Parsing:
CliParserusesclapto match OS arguments against defined subcommands and flags. - Instantiation: An instance of the
Clistruct is created, representing the user's intent. - Evaluation Conversion: The
Clistruct is converted intoEvalArgsviato_eval_args. This step involves resolving environment variables, directory paths (in/out), and determining the execution phase. - Directory Resolution: The system determines the project directory and target paths (e.g.,
target/) before execution.
The flow ensures that every command has access to a consistent set of evaluation arguments, regardless of the specific subcommand used. Sources: crates/dbt-clap-core/src/lib.rs:218-230, crates/dbt-clap-core/src/lib.rs:271-285
Global Flags and Common Arguments
The CommonArgs struct defines flags available across almost all dbt commands. These are grouped into logical headings in the --help output such as Project, Selection, and Execution. Sources: crates/dbt-clap-core/src/lib.rs:65-72, crates/dbt-clap-core/src/lib.rs:657-660
Key Global Configuration
| Flag | Environment Variable | Description |
|---|---|---|
--project-dir | DBT_PROJECT_DIR | Directory to load the dbt project from. |
--target | DBT_TARGET | The specific profile target to execute against. |
--profiles-dir | DBT_PROFILES_DIR | Directory containing profiles.yml. |
--vars | N/A | Supply YAML/JSON variable bindings. |
--select | N/A | Filter nodes to run (models, tests, etc.). |
--exclude | N/A | Exclude specific nodes from execution. |
--threads | N/A | Number of concurrent threads for execution. |
Sources: crates/dbt-clap-core/src/lib.rs:661-736
Core Command Suite
The CLI supports a comprehensive set of subcommands for the analytics lifecycle. Commands are categorized as either "project commands" (requiring a dbt_project.yml) or "non-project commands." Sources: crates/dbt-clap-core/src/lib.rs:257-269
Project Execution Commands
- Run: Executes models defined in the project.
- Build: Performs a multi-phase execution including seeds, snapshots, models, and tests.
- Test: Runs data tests and unit tests.
- Compile: Generates executable SQL from Jinja templates.
- Seed: Loads CSV files into the database.
- Snapshot: Executes snapshot logic for state tracking.
Sources: crates/dbt-clap-core/src/lib.rs:518-540, crates/dbt-clap-core/src/lib.rs:596-610
Utility & Management Commands
- Init: Initializes a new dbt project. It can skip profile setup or use specific templates like
jaffle_shop. Sources: crates/dbt-clap-core/src/lib.rs:1140-1160 - Deps: Manages project dependencies and packages. Sources: crates/dbt-clap-core/src/lib.rs:356-368
- Docs Serve: Starts a local web server to host the project documentation. It defaults to port 8580. Sources: crates/dbt-docs-server/README.md:85-100, crates/dbt-clap-core/src/lib.rs:634-645
- Login: Manages authentication status for platform features. Sources: crates/dbt-clap-core/src/lib.rs:612-620
Extension Interface
The CLI is designed to be extensible through the AbstractExtensionCommand trait and CliFeature hooks. This allows components like dbt-sa (Standalone Analyzer) or dbt-fusion to inject custom subcommands and logic into the standard dbt interface. Sources: crates/dbt-features/src/cli.rs:25-35, crates/dbt-features/src/cli.rs:107-112
Hook System
Extensions can hook into various stages of the CLI lifecycle:
will_execute: Called before any tasks are scheduled.did_resolve_project: Called after the manifest and nodes have been resolved.will_run_tasks: Called just before task execution.did_compile: Called after successful compilation.
Integration with MiniJinja
Dbt-core utilizes minijinja-cli for Jinja2 template evaluation. This interface allows for direct expression evaluation (--expr) and template rendering from strings (--template) or files. It supports various input formats including JSON, YAML, TOML, and INI. Sources: crates/dbt-jinja/minijinja-cli/src/command.rs:18-35, crates/dbt-jinja/minijinja-cli/src/command.rs:155-165
Conclusion
The CLI Commands & Interface provide a unified entry point for all project operations. By leveraging a structured parsing system and a flexible hook architecture, the interface supports both standard dbt Core functionality and advanced Fusion engine features while maintaining high execution performance through its Rust implementation. Sources: crates/dbt-main/src/dbt_lib.rs:77-85, README.md:20-25