Install dbt Cloud CLI

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

Diagram of how the dbt Cloud CLI works with dbt Cloud's infrastructure to run dbt commands from your local command line.

Prerequisites

The dbt Cloud CLI is available in all deployment regions and for both multi-tenant and single-tenant accounts.

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 installation.

macOS (brew)

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.

1. Verify that you don't already have dbt Core installed by running the following command:

which dbt

If the output is dbt not found, then that confirms you don't have it installed.

Run pip uninstall dbt to uninstall dbt Core

If you've installed dbt Core globally in some other way, uninstall it first before proceeding:

pip uninstall dbt

2. 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, add and install the dbt Cloud CLI as a package:

     brew tap dbt-labs/dbt-cli
     brew install dbt
     If you have multiple taps, use brew install dbt-labs/dbt-cli/dbt.

3. 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 run dbt deps if you make any changes to your packages.yml file.

4. Clone your repository to your local computer using git clone. For example, to clone a GitHub repo using HTTPS format, run git clone https://github.com/YOUR-USERNAME/YOUR-REPOSITORY.

5. After cloning your repo, configure the dbt Cloud CLI for your dbt Cloud project. This lets you run dbt commands like dbt environment show to view your dbt Cloud configuration or dbt compile to compile your project and validate models and tests. You can also add, edit, and synchronize files with your repo.

Windows (native executable)

Refer to the FAQs if your operating system runs into path conflicts.

1. Download the latest Windows release for your platform from GitHub.

2. Extract the dbt.exe executable into the same folder as your dbt project.

info

Advanced users can configure multiple projects to use the same dbt Cloud CLI by:

1. Placing the executable file (.exe) in the "Program Files" folder
2. Adding it to their Windows PATH environment variable
3. Saving it where needed

Note that if you're using VS Code, you must restart it to pick up modified environment variables.

3. 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 run dbt deps if you make any changes to your packages.yml file.

4. Clone your repository to your local computer using git clone. For example, to clone a GitHub repo using HTTPS format, run git clone https://github.com/YOUR-USERNAME/YOUR-REPOSITORY.

5. After cloning your repo, configure the dbt Cloud CLI for your dbt Cloud project. This lets you run dbt commands like dbt environment show to view your dbt Cloud configuration or dbt compile to compile your project and validate models and tests. You can also add, edit, and synchronize files with your repo.

Linux (native executable)

Refer to the FAQs if your operating system runs into path conflicts.

1. Download the latest Linux release for your platform from GitHub. (Pick the file based on your CPU architecture)

2. 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

info

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.

3. 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 run dbt deps if you make any changes to your packages.yml file.

4. Clone your repository to your local computer using git clone. For example, to clone a GitHub repo using HTTPS format, run git clone https://github.com/YOUR-USERNAME/YOUR-REPOSITORY.

5. After cloning your repo, configure the dbt Cloud CLI for your dbt Cloud project. This lets you run dbt commands like dbt environment show to view your dbt Cloud configuration or dbt compile to compile your project and validate models and tests. You can also add, edit, and synchronize files with your repo.

Existing dbt Core users (pip)

If you already have dbt Core installed, the dbt Cloud CLI may conflict. Here are some considerations:

• Prevent conflicts
  Use both the dbt Cloud CLI and dbt Core with pip and create a new virtual environment.
  
  
• Use both dbt Cloud CLI and dbt Core with brew or native installs
  If you use Homebrew, consider aliasing the dbt Cloud CLI as "dbt-cloud" to avoid conflict. For more details, check the FAQs if your operating system experiences path conflicts.
  
  
• Reverting to dbt Core from the dbt Cloud CLI
  If you've already installed the dbt Cloud CLI and need to switch back to dbt Core:
  
  • Uninstall the dbt Cloud CLI using the command: pip uninstall dbt
  • Reinstall dbt Core using the following command, replacing "adapter_name" with the appropriate adapter name:

    python -m pip install dbt-adapter_name --force-reinstall
    For example, if I used Snowflake as an adapter, I would run: python -m pip install dbt-snowflake --force-reinstall

---

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.

1. Create a new virtual environment named "dbt-cloud" with this command:

   python3 -m venv dbt-cloud

2. Activate the virtual environment each time you create a shell window or session, depending on your operating system:

   • For Mac and Linux, use: source dbt-cloud/bin/activate
     
   • For Windows, use: dbt-env\Scripts\activate

3. (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

1. (Optional) If you already have dbt Core installed, this installation will override that package. Check your dbt Core version in case you need to reinstall it later by running the following command :

dbt --version

2. Make sure you're in your virtual environment and run the following command to install the dbt Cloud CLI:

pip install dbt --no-cache-dir

If there are installation issues, running the command with the --force-reinstall argument might help:

pip install dbt --no-cache-dir --force-reinstall

3. (Optional) To revert to dbt Core, first uninstall both the dbt Cloud CLI and dbt Core. Then reinstall dbt Core.

pip uninstall dbt-core dbt
pip install dbt-adapter_name --force-reinstall

4. Clone your repository to your local computer using git clone. For example, to clone a GitHub repo using HTTPS format, run git clone https://github.com/YOUR-USERNAME/YOUR-REPOSITORY.

5. After cloning your repo, configure the dbt Cloud CLI for your dbt Cloud project. This lets you run dbt commands like dbt environment show to view your dbt Cloud configuration or dbt compile to compile your project and validate models and tests. You can also add, edit, and synchronize files with your repo.

Update dbt Cloud CLI

The following instructions explain how to update the dbt Cloud CLI to the latest version depending on your operating system.

macOS (brew)

To update the dbt Cloud CLI, run brew update and then brew upgrade dbt.

Windows (executable)

To update, follow the same process explained in Windows and replace the existing dbt.exe executable with the new one.

Linux (executable)

To update, follow the same process explained in Linux and replace the existing dbt executable with the new one.

Existing dbt Core users (pip)

To update:

• Make sure you're in your virtual environment
• Run python -m pip install --upgrade dbt.

VS Code extension beta

Visual Studio (VS) Code extensions enhance command line tools by adding extra functionalities. Power user for dbt Core and dbt Cloud is a common extension used to enhance your dbt development with VS Code.

You can use the dbt Cloud CLI with Power User for dbt Core and dbt Cloud by following the instructions here.

The Power User extension will handle installing the Cloud CLI on your behalf.

FAQs

 What's the difference between the dbt Cloud CLI and dbt Core?

The dbt Cloud CLI and dbt Core, an open-source project, are both command line tools that enable you to run dbt commands.

The key distinction is the dbt Cloud CLI is tailored for dbt Cloud's infrastructure and integrates with all its features.

 How do I run both the dbt Cloud CLI and dbt Core?

For compatibility, both the dbt Cloud CLI and dbt Core are invoked by running 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:

1. Install using the pip3 install dbt pip command.
2. Install natively, ensuring you either deactivate the virtual environment containing dbt Core or create an alias for the dbt Cloud CLI.
3. (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.

 How to create an alias?

To create an alias for the dbt Cloud CLI:

1. Open your shell's profile configuration file. Depending on your shell and system, this could be ~/.bashrc, ~/.bash_profile, ~/.zshrc, or another file.
   

2. Add an alias that points to the dbt Cloud CLI binary. For example:alias dbt-cloud="path_to_dbt_cloud_cli_binary

   Replace path_to_dbt_cloud_cli_binary with the actual path to the dbt Cloud CLI binary, which is /opt/homebrew/bin/dbt. With this alias, you can use the command dbt-cloud to invoke the dbt Cloud CLI.
   

3. Save the file and then either restart your shell or run source on the profile file to apply the changes. As an example, in bash you would run: source ~/.bashrc
   

4. Test and use the alias to run commands:
   

   • To run the dbt Cloud CLI, use the dbt-cloud command: dbt-cloud command_name. Replace 'command_name' with the specific dbt command you want to execute.
     
   • To run the dbt Core, use the dbt command: dbt command_name. Replace 'command_name' with the specific dbt command you want to execute.
     

This alias will allow you to use the dbt-cloud command to invoke the dbt Cloud CLI while having dbt Core installed natively.

 Why am I receiving a `Stuck session` error when trying to run a new command?

The dbt Cloud CLI allows only one command that writes to the data warehouse at a time. If you attempt to run multiple write commands simultaneously (for example, dbt run and dbt build), you will encounter a stuck session error. To resolve this, cancel the specific invocation by passing its ID to the cancel command. For more information, refer to parallel execution.

I'm getting a "Session occupied" error in dbt Cloud CLI?

If you're receiving a Session occupied error in the dbt Cloud CLI or if you're experiencing a long-running session, you can use the dbt invocation list command in a separate terminal window to view the status of your active session. This helps debug the issue and identify the arguments that are causing the long-running session.

To cancel an active session, use the Ctrl + Z shortcut.

To learn more about the dbt invocation command, see the dbt invocation command reference.

Alternatively, you can reattach to your existing session with dbt reattach and then press Control-C and choose to cancel the invocation.