{"id":8075,"library":"dbt","title":"dbt Cloud CLI","description":"The `dbt` package on PyPI refers to the dbt Cloud CLI, a tool for executing dbt Core commands within the context of dbt Cloud environments. It acts as a wrapper, facilitating connection to dbt Cloud for running SQL transformations and managing data models. The current version is 1.0.0.40.16. While dbt Core itself has a regular release cadence (monthly minor, quarterly major), the dbt Cloud CLI releases are tied to dbt Cloud infrastructure updates, typically updated frequently.","status":"active","version":"1.0.0.40.16","language":"en","source_language":"en","source_url":"https://github.com/dbt-cloud/dbt-cloud-cli","tags":["elt","data transformation","sql","cli","dbt cloud","data modeling"],"install":[{"cmd":"pip install dbt","lang":"bash","label":"Install dbt Cloud CLI"}],"dependencies":[],"imports":[{"note":"The `dbt` package on PyPI is the `dbt Cloud CLI`, primarily designed for command-line execution. Programmatic interaction with dbt Core functionality should typically use `dbt-core` (e.g., `pip install dbt-core`) and its respective APIs. The `dbt` CLI is best invoked via `subprocess` for automation.","wrong":"from dbt import project","symbol":"CLI commands (subprocess)","correct":"import subprocess; subprocess.run([\"dbt\", \"run\"])"}],"quickstart":{"code":"import subprocess\nimport os\n\n# Ensure dbt is in your PATH, or specify the full path to the executable.\n# This example assumes 'dbt' is accessible via PATH.\n\n# For dbt Cloud CLI, you'll typically interact with an existing dbt Cloud project.\n# This simple debug command checks dbt and its environment.\n# Real world usage involves `dbt run`, `dbt test`, etc., usually within a dbt project directory.\n\n# Example: Run dbt debug\ntry:\n    print(\"Running 'dbt debug'...\")\n    # The check=True argument raises an exception for non-zero exit codes\n    result = subprocess.run([\"dbt\", \"debug\"], capture_output=True, text=True, check=True)\n    print(\"dbt debug output:\\n\", result.stdout)\n    if result.stderr:\n        print(\"dbt debug errors/warnings:\\n\", result.stderr)\n\n    # Example of a command that would require a dbt project and connection (commented out)\n    # To run this, you'd need to be in a dbt project directory with configured profiles.\n    # print(\"\\nAttempting 'dbt seed' (requires project & connection)...\\n\")\n    # # Ensure DBT_CLOUD_API_KEY is set in your environment if interacting with dbt Cloud\n    # # os.environ['DBT_CLOUD_API_KEY'] = os.environ.get('DBT_CLOUD_API_KEY', 'your_dbt_cloud_api_key')\n    # seed_result = subprocess.run([\"dbt\", \"seed\"], capture_output=True, text=True, check=True)\n    # print(\"dbt seed output:\\n\", seed_result.stdout)\n\nexcept subprocess.CalledProcessError as e:\n    print(f\"Error running dbt command (exit code {e.returncode}): {e.cmd}\")\n    print(f\"STDOUT:\\n{e.stdout}\")\n    print(f\"STDERR:\\n{e.stderr}\")\nexcept FileNotFoundError:\n    print(\"Error: 'dbt' command not found. Make sure dbt Cloud CLI is installed and in your system PATH.\")\nexcept Exception as e:\n    print(f\"An unexpected error occurred: {e}\")\n","lang":"python","description":"Demonstrates how to invoke the `dbt` (dbt Cloud CLI) command-line tool using Python's `subprocess` module. This is the primary way to interact with the dbt Cloud CLI programmatically. The `dbt debug` command checks the environment without requiring a full dbt project, making it suitable for a basic quickstart."},"warnings":[{"fix":"For programmatic interaction with dbt's core functionality (e.g., parsing SQL, executing models outside of dbt Cloud), install `dbt-core` via `pip install dbt-core`. Use the `dbt` (dbt Cloud CLI) package only when you intend to manage dbt Cloud resources or run jobs in dbt Cloud environments.","message":"The `dbt` PyPI package installs the `dbt Cloud CLI`, which is a distinct product from `dbt-core`. `dbt-core` is the open-source data transformation framework, while `dbt Cloud CLI` is designed specifically for interaction with dbt Cloud environments.","severity":"gotcha","affected_versions":"All versions of `dbt` (dbt Cloud CLI) and `dbt-core`."},{"fix":"Always consult the `dbt-core` release notes for the version used by your dbt Cloud environment (or specified in your `dbt_project.yml` if using local execution with the CLI). Test your dbt projects thoroughly when upgrading `dbt` (dbt Cloud CLI) or changing dbt Cloud environments.","message":"While `dbt` (dbt Cloud CLI) aims for stability, its underlying `dbt-core` version is updated. Breaking changes in `dbt-core` (e.g., changes to macro signatures, adapter interfaces, `dbt_project.yml` schema) will directly affect how your dbt projects run via the dbt Cloud CLI.","severity":"breaking","affected_versions":"All versions of `dbt` (dbt Cloud CLI) and corresponding `dbt-core` versions."},{"fix":"Ensure `DBT_CLOUD_API_KEY` is set in your environment with a valid dbt Cloud API key. For CI/CD, use secrets management to securely provide this key.","message":"To interact with dbt Cloud resources (e.g., run jobs, list projects), the `dbt` Cloud CLI requires authentication, typically via a dbt Cloud API key set as an environment variable (`DBT_CLOUD_API_KEY`). Without it, commands interacting with dbt Cloud will fail.","severity":"gotcha","affected_versions":"All versions."}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Ensure `pip install dbt` completed successfully and that the Python scripts directory (e.g., `~/.local/bin` on Linux/macOS, `Scripts` in Python install dir on Windows) is included in your system's PATH. Restart your terminal after modifying PATH.","cause":"The `dbt` Cloud CLI executable is not in the system's PATH, or it was not installed correctly.","error":"`dbt` command not found"},{"fix":"Navigate to your dbt project's root directory before running the command, or specify the `--project-dir` flag: `dbt run --project-dir /path/to/my/project`.","cause":"Many `dbt` commands (e.g., `dbt run`, `dbt test`, `dbt build`) must be executed from within a dbt project directory (i.e., a directory containing `dbt_project.yml` and its subdirectories).","error":"Runtime Error: Could not find dbt_project.yml file."},{"fix":"Verify your `profiles.yml` (located at `~/.dbt/profiles.yml` by default) has correct connection details for the specified target. Check firewall rules, network connectivity, and credentials (e.g., API keys, service account files, user/password).","cause":"The dbt Cloud CLI could not establish a connection to your data warehouse, usually due to incorrect profile configuration (`profiles.yml`) or network issues. 'XXX' represents a database type like 'snowflake', 'bigquery', etc.","error":"Database Error: Could not connect to adapter type 'XXX'."}]}