Skip to main content

Install dbt Cloud CLI

Public preview functionality

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.


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

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.

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:

    which dbt
    • If you see a dbt not found, you're good to go. If the dbt help text appears, use pip uninstall dbt to remove dbt Core from your system.
  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

  5. After cloning your repo, configure the dbt Cloud CLI for your dbt Cloud project. This lets you run dbt commands like 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.

During the public preview period, we recommend updating before filing a bug report. This is because the API is subject to breaking changes.

To update the dbt Cloud CLI, run brew upgrade dbt. (You can also use brew install dbt).

Using VS Code extensions

Visual Studio (VS) Code extensions enhance command line tools by adding extra functionalities. The dbt Cloud CLI is fully compatible with dbt Core, however it doesn't support some dbt Core APIs required by certain tools, for example VS Code extensions.

To use these extensions, such as dbt-power-user, with the dbt Cloud CLI, you can install it using Homebrew (along with dbt Core) and create an alias to run the dbt Cloud CLI as dbt-cloud. This allows dbt-power-user to continue to invoke dbt Core under the hood, alongside the dbt Cloud CLI.


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 Session occupied error?
If you've ran a dbt command and receive a Session occupied error, you can reattach to your existing session with dbt reattach and then press Control-C and choose to cancel the invocation.