Install dbt Cloud CLI
The dbt Cloud CLI is currently in public preview. Share feedback or request features you'd like to see on the dbt community Slack.
dbt Cloud natively supports developing using a command line (CLI), empowering team members to contribute with enhanced flexibility and collaboration. The dbt Cloud CLI allows you to run dbt commands against your dbt Cloud development environment from your local command line.
dbt commands are run against dbt Cloud's infrastructure and benefit from:
- Secure credential storage in the dbt Cloud platform.
- Automatic deferral of build artifacts to your Cloud project's production environment.
- Speedier, lower-cost builds.
- Support for dbt Mesh (cross-project
ref
), - Significant platform improvements, to be released over the coming months.
Prerequisites
The dbt Cloud CLI is available in all deployment regions and for both multi-tenant and single-tenant accounts (Azure single-tenant not supported at this time).
- Ensure you are using dbt version 1.5 or higher. Refer to dbt Cloud versions to upgrade.
- Avoid using SSH tunneling for Postgres and Redshift connections.
- Avoid using PrivateLink.
Install dbt Cloud CLI
You can install the dbt Cloud CLI on the command line by using one of these methods.
View a video tutorial for a step-by-step guide to installing
- macOS (brew)
- Windows (native executable)
- Linux (native executable)
- Existing dbt Core users (pip)
Before you begin, make sure you have Homebrew installed in your code editor or command line terminal. Refer to the FAQs if your operating system runs into path conflicts.
Run the following command to verify that you don't already have dbt Core installed:
which dbt
- This should return a
dbt not found
. If the dbt help text appears, usepip uninstall dbt
to remove dbt Core from your machine.
- This should return a
Install the dbt Cloud CLI with Homebrew:
- First, remove the dbt-labs tap, the separate repository for packages, from Homebrew. This prevents Homebrew from installing packages from that repository:
brew untap dbt-labs/dbt
- Then run
brew tap
to add and install the dbt Cloud CLI as a package:brew tap dbt-labs/dbt-cli
- Lastly, install the dbt Cloud CLI with Homebrew:
brew install dbt
- First, remove the dbt-labs tap, the separate repository for packages, from Homebrew. This prevents Homebrew from installing packages from that repository:
Verify your installation by running
dbt --help
in the command line. If you see the following output, your installation is correct:The dbt Cloud CLI - an ELT tool for running SQL transformations and data models in dbt Cloud...
If you don't see this output, check that you've deactivated pyenv or venv and don't have a global dbt version installed.
- Note that you no longer need to run the
dbt deps
command when your environment starts. This step was previously required during initialization. However, you should still rundbt deps
if you make any changes to yourpackages.yml
file.
- Note that you no longer need to run the
After you've verified the installation, configure the dbt Cloud CLI for your dbt Cloud project and use it to run dbt commands similar to dbt Core. For example, execute
dbt compile
to compile a project using dbt Cloud and validate your models and tests.- If you're using the dbt Cloud CLI, you can connect to your data platform directly in the dbt Cloud interface and don't need a
profiles.yml
file locally on your machine.
- If you're using the dbt Cloud CLI, you can connect to your data platform directly in the dbt Cloud interface and don't need a
Refer to the FAQs if your operating system runs into path conflicts.
Download the latest Windows release for your platform from GitHub.
Extract the
dbt.exe
executable into the same folder as your dbt project.
Advanced users can configure multiple projects to use the same dbt Cloud CLI by placing the executable in the Program Files folder and adding it to their Windows PATH environment variable.
Note that if you are using VS Code, you must restart it to pick up modified environment variables.
Verify your installation by running
./dbt --help
in the command line. If you see the following output, your installation is correct:The dbt Cloud CLI - an ELT tool for running SQL transformations and data models in dbt Cloud...
If you don't see this output, check that you've deactivated pyenv or venv and don't have a global dbt version installed.
- Note that you no longer need to run the
dbt deps
command when your environment starts. This step was previously required during initialization. However, you should still rundbt deps
if you make any changes to yourpackages.yml
file.
- Note that you no longer need to run the
After installation, configure the dbt Cloud CLI for your dbt Cloud project and use it to run dbt commands similar to dbt Core. For example, execute
dbt compile
, to compile a project using dbt Cloud and confirm that it works.- If you're using the dbt Cloud CLI, you can connect to your data platform directly in the dbt Cloud interface and don't need a
profiles.yml
file locally on your machine.
- If you're using the dbt Cloud CLI, you can connect to your data platform directly in the dbt Cloud interface and don't need a
Refer to the FAQs if your operating system runs into path conflicts.
Download the latest Linux release for your platform from GitHub. (Pick the file based on your CPU architecture)
Extract the
dbt-cloud-cli
binary to the same folder as your dbt project.tar -xf dbt_0.29.9_linux_amd64.tar.gz
./dbt --version
Advanced users can configure multiple projects to use the same Cloud CLI executable by adding it to their PATH environment variable in their shell profile.
Verify your installation by running
./dbt --help
in the command line. If you see the following output, your installation is correct:The dbt Cloud CLI - an ELT tool for running SQL transformations and data models in dbt Cloud...
If you don't see this output, check that you've deactivated pyenv or venv and don't have a global dbt version installed.
- Note that you no longer need to run the
dbt deps
command when your environment starts. This step was previously required during initialization. However, you should still rundbt deps
if you make any changes to yourpackages.yml
file.
- Note that you no longer need to run the
After installation, configure the dbt Cloud CLI for your dbt Cloud project and use it to run dbt commands similar to dbt Core. For example, execute
dbt compile
, to compile a project using dbt Cloud and confirm that it works.- If you're using the dbt Cloud CLI, you can connect to your data platform directly in the dbt Cloud interface and don't need a
profiles.yml
file locally on your machine.
- If you're using the dbt Cloud CLI, you can connect to your data platform directly in the dbt Cloud interface and don't need a
To prevent overwriting dbt Core, avoid installing the dbt Cloud CLI with pip. Instead, consider using the native installation method and configuring your PATH or create a new virtual environment.
If you've already installed the dbt Cloud CLI and need to switch back to dbt Core, uninstall the dbt Cloud CLI, and follow the dbt Core installation instructions.
You can also have both dbt Cloud CLI and dbt Core installed simultaneously. To avoid conflicts, alias the dbt Cloud CLI as dbt-cloud
. For more details, check the FAQs if your operating system experiences path conflicts.
Before installing the dbt Cloud CLI, make sure you have Python installed and your virtual environment venv or pyenv . If you already have a Python environment configured, you can skip to the pip installation step.
Install a virtual environment
We recommend using virtual environments (venv) to namespace cloud-cli
.
Create a new venv:
python3 -m venv dbt-cloud
Activate the virtual environment each time you create a shell window or session:
source dbt-cloud/bin/activate # activate the environment for Mac and Linux OR
dbt-env\Scripts\activate # activate the environment for Windows(Mac and Linux only) Create an alias to activate your dbt environment with every new shell window or session. You can add the following to your shell's configuration file (for example, $HOME/.bashrc, $HOME/.zshrc) while replacing
<PATH_TO_VIRTUAL_ENV_CONFIG>
with the path to your virtual environment configuration:alias env_dbt='source <PATH_TO_VIRTUAL_ENV_CONFIG>/bin/activate'
Install dbt Cloud CLI in pip
(Optional) If you already have dbt Core installed, this installation will override that package. Note your dbt Core version in case you need to reinstall it later:
dbt --version
Make sure you're in your virtual environment and run the following command to install the dbt Cloud CLI:
pip3 install dbt
(Optional) To revert back to dbt Core, first uninstall both the dbt Cloud CLI and dbt Core
Reinstall dbt Core using the version from Step 2.
pip3 uninstall dbt-core dbt
pip3 install dbt-core==VERSIONAfter you've verified the installation, configure the dbt Cloud CLI for your dbt Cloud project and use it to run dbt commands similar to dbt Core. For example, execute
dbt compile
to compile a project using dbt Cloud and validate your models and tests.- If you're using the dbt Cloud CLI, you can connect to your data platform directly in the dbt Cloud interface and don't need a
profiles.yml
file locally on your machine.
- If you're using the dbt Cloud CLI, you can connect to your data platform directly in the dbt Cloud interface and don't need a
Update dbt Cloud CLI
The following instructions explain how to update the dbt CLoud CLI to the latest version depending on your operating system.
During the public preview period, we recommend updating before filing a bug report. This is because the API is subject to breaking changes.
- macOS (brew)
- Windows (executable)
- Linux (executable)
- Existing dbt Core users (pip)
To update the dbt Cloud CLI, run brew upgrade dbt
. (You can also use brew install dbt
).
To update, follow the same process explained in Windows and replace the existing dbt.exe
executable with the new one.
To update, follow the same process explained in Windows and replace the existing dbt
executable with the new one.
To update:
- Make sure you're in your virtual environment
- Run
pip install --upgrade dbt
.
FAQs
What's the difference between the dbt Cloud CLI and dbt Core?
How do I run both the dbt Cloud CLI and dbt Core?
dbt
. This can create path conflicts if your operating system selects one over the other based on your $PATH environment variable (settings).If you have dbt Core installed locally, either:
Install using pip.
Install natively, but ensure that you deactivate your Python environment or uninstall it using
pip uninstall dbt
before proceeding.(Advanced users) Install natively, but modify the $PATH environment variable to correctly point to the dbt Cloud CLI binary to use both dbt Cloud CLI and dbt Core together.
You can always uninstall the dbt Cloud CLI to return to using dbt Core.
Why am I receiving a Session occupied
error?
Session occupied
error, you can reattach to your existing session with dbt reattach
and then press Control-C
and choose to cancel the invocation.