Configure and use the 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.

Prerequisites

• You must set up a project in dbt Cloud.
  • Note — 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.
• You must have your personal development credentials set for that project. The dbt Cloud CLI will use these credentials, stored securely in dbt Cloud, to communicate with your data platform.
• You must be on dbt version 1.5 or higher. Refer to dbt Cloud versions to upgrade.

Configure the dbt Cloud CLI

Once you install the dbt Cloud CLI, you need to configure it to connect to a dbt Cloud project.

1. Ensure you meet the prerequisites above and go to dbt Cloud to download your credentials by clicking on the Try the dbt Cloud CLI banner.

   Region URLs to download credentials

   You can also download the credentials from the links provided based on your region:

   • North America: https://cloud.getdbt.com/cloud-cli
   • EMEA: https://emea.dbt.com/cloud-cli
   • APAC: https://au.dbt.com/cloud-cli
   • North American Cell 1: https:/ACCOUNT_PREFIX.us1.dbt.com/cloud-cli
   • Single-tenant: https://YOUR_ACCESS_URL/cloud-cli

2. Save the config file to your local computer's filesystem. Make sure to store your dbt_cloud.yml config file in a safe place as it contains API keys.

   • Mac or Linux: ~/.dbt/dbt_cloud.yml
   • Windows: C:\Users\yourusername\.dbt\dbt_cloud.yml

   The config file looks like this:

   version: "1"
   context:
       active-project: "<project id from the list below>"
       active-host: "<active host from the list>"
       defer-env-id: "<optional defer environment id>"
   projects:
   - project-id: "<project-id>"
       account-host: "<account-host>"
       api-key: "<user-api-key>"
   
   - project-id: "<project-id>"
       account-host: "<account-host>"
       api-key: "<user-api-key>"

3. After downloading the config file, navigate to a dbt project in your terminal:

   cd ~/dbt-projects/jaffle_shop

4. In your dbt_project.yml file, ensure you have or include a dbt-cloud section with a project-id field. The project-id field contains the dbt Cloud project ID you want to use.

   # dbt_project.yml
   name:
   version:
   # Your project configs...
   
   dbt-cloud: 
       project-id: PROJECT_ID
   • To find your project ID, select Develop in the dbt Cloud navigation menu. You can use the URL to find the project ID. For example, in https://cloud.getdbt.com/develop/26228/projects/123456, the project ID is 123456.

5. You should now be able to use the dbt Cloud CLI and run dbt commands like dbt environment show to view your dbt Cloud configuration details or dbt compile to compile models in your dbt project.

With your repo recloned, you can add, edit, and sync files with your repo.

Set environment variables

To set environment variables in the dbt Cloud CLI for your dbt project:

1. Select the gear icon on the upper right of the page.
2. Then select Profile Settings, then Credentials.
3. Click on your project and scroll to the Environment Variables section.
4. Click Edit on the lower right and then set the user-level environment variables.
   • Note, when setting up the dbt Semantic Layer, using environment variables like {{env_var('DBT_WAREHOUSE')}} is not supported. You should use the actual credentials instead.

Use the dbt Cloud CLI

The dbt Cloud CLI uses the same set of dbt commands and MetricFlow commands as dbt Core to execute the commands you provide. For example, use the dbt environment command to view your dbt Cloud configuration details. With the dbt Cloud CLI, you can:

• Run multiple invocations in parallel and ensure safe parallelism, which is currently not guaranteed by dbt-core.
• Automatically defers build artifacts to your Cloud project's production environment.
• Supports project dependencies, which allows you to depend on another project using the metadata service in dbt Cloud.
  • Project dependencies instantly connect to and reference (or ref) public models defined in other projects. You don't need to execute or analyze these upstream models yourself. Instead, you treat them as an API that returns a dataset.

Use the --help flag

As a tip, most command-line tools have a --help flag to show available commands and arguments. Use the --help flag with dbt in two ways:

• dbt --help: Lists the commands available for dbt
  
• dbt run --help: Lists the flags available for the run command