Configure and use the dbt Cloud CLI
Learn how to configure the dbt Cloud CLI for your dbt Cloud project to 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'll also 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), and more.
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.
- 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
- 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.
In dbt Cloud, navigate to Develop and click Configure dbt Cloud CLI to download your
dbt_cloud.yml
credentials file.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
Save the
dbt_cloud.yml
file in the.dbt
directory, which stores your dbt Cloud CLI configuration. Store it in a safe place as it contains API keys. Check out the FAQs to learn how to create a.dbt
directory and move thedbt_cloud.yml
file.- 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>"- Mac or Linux:
After downloading the config file and creating your directory, navigate to a dbt project in your terminal:
cd ~/dbt-projects/jaffle_shop
In your
dbt_project.yml
file, ensure you have or include adbt-cloud
section with aproject-id
field. Theproject-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 is123456
.
- 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
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 ordbt 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:
- Select the gear icon on the upper right of the page.
- Then select Profile Settings, then Credentials.
- Click on your project and scroll to the Environment Variables section.
- 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.
- Note, when setting up the dbt Semantic Layer, using environment variables like
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.
- Project dependencies instantly connect to and reference (or
--help
flagAs 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 dbtdbt run --help
: Lists the flags available for therun
command