updates

dbt-labs · Oct 10, 2023 · 21b1db8 · 21b1db8
1 parent 94562f5
commit 21b1db8
Show file tree

Hide file tree

Showing 5 changed files with 91 additions and 68 deletions.
diff --git a/website/docs/docs/cloud/about-cloud-develop.md b/website/docs/docs/cloud/about-cloud-develop.md
@@ -9,7 +9,7 @@ hide_table_of_contents: true
 
 dbt Cloud offers a fast and reliable way to work on your dbt project. It runs dbt Core in a hosted (single or multi-tenant) environment. You can develop in your browser using an integrated development environment (IDE) or in a dbt Cloud-powered command line interface (CLI):
 
-<div className="grid--3-col">
+<div className="grid--2-col" >
 
 <Card
     title="dbt Cloud CLI"
@@ -27,4 +27,5 @@ dbt Cloud offers a fast and reliable way to work on your dbt project. It runs db
 
 The following sections provide detailed instructions on setting up the dbt Cloud CLI and dbt Cloud IDE. To get started with dbt development, you'll need a [developer](/docs/cloud/manage-access/seats-and-users) account. For a more comprehensive guide about developing in dbt, refer to our [quickstart guides](/quickstarts).
 
-[^1]: The dbt Cloud CLI and the open-sourced dbt Core are both command line tools that let you run dbt commands. The key distinction is the dbt Cloud CLI is tailored for dbt Cloud's infrastructure and integrates with all its [features](/docs/cloud/about-cloud/dbt-cloud-features).
+---------
+**Note**: The dbt Cloud CLI and the open-sourced dbt Core are both command line tools that let you run dbt commands. The key distinction is the dbt Cloud CLI is tailored for dbt Cloud's infrastructure and integrates with all its [features](/docs/cloud/about-cloud/dbt-cloud-features).
diff --git a/website/docs/docs/cloud/cloud-cli-installation.md b/website/docs/docs/cloud/cloud-cli-installation.md
@@ -6,12 +6,9 @@ description: "Instructions for installing and configuring dbt Cloud CLI"
 pagination_next: "docs/cloud/configure-cloud-cli"
 ---
 
+import CloudCLIFlag from '/snippets/_cloud-cli-flag.md';
 
-:::info Public preview functionality
-
-The dbt Cloud CLI is currently in [public preview](/docs/dbt-versions/product-lifecycles#dbt-cloud). Share feedback or request features you'd like to see on the [dbt community Slack](https://getdbt.slack.com/archives/C05M77P54FL).
-
-::: 
+<CloudCLIFlag/>
 
 
 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.
@@ -43,31 +40,31 @@ To revert back to dbt Core, follow the install instructions for dbt Core.
 
 ::: 
 
-This guide is for users who already have a Python environment configured.
+This tab is for users who already have a Python environment configured.
 
 1. Ensure you have Python installed and your local venv or pyenv activated.
 
 2. (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:
 
-```bash
-dbt --version
-```
+  ```bash
+  dbt --version
+  ```
 
 3. Run the following command to install the dbt Cloud CLI
 
-```bash
-pip3 install dbt
-```
+  ```bash
+  pip3 install dbt
+  ```
 
 4. (Optional) To revert back to dbt Core, first uninstall both the dbt Cloud CLI and dbt Core
 5. Then reinstall dbt Core using the version from Step 2.
 
-```bash
-pip3 uninstall dbt-core dbt
-pip3 install dbt-core==VERSION
-```
-</TabItem>
+  ```bash
+  pip3 uninstall dbt-core dbt
+  pip3 install dbt-core==VERSION
+  ```
 
+</TabItem>
 
 <TabItem value="brew" label="macOS (brew)">
 
@@ -76,20 +73,20 @@ Before you begin, make sure you have [Homebrew installed](http://brew.sh/) in yo
 
 1. Run the following command to verify that there is no conflict with a dbt Core installation on your system:
 
-```bash
-which dbt
-```
+  ```bash
+  which dbt
+  ```
    - This should return a `dbt not found`. If the dbt help text appears, use `pip uninstall dbt` to deactivate dbt Core from your machine.
 
 2. Install the dbt Cloud CLI with Homebrew: 
 
-```bash
-brew tap dbt-labs/dbt-cli
-brew install dbt
-```
+  ```bash
+  brew tap dbt-labs/dbt-cli
+  brew install dbt
+  ```
 
 3. Verify the installation by running `dbt --help` from the command line. If the help text doesn't indicate that you're using the dbt Cloud CLI, make sure you've deactivated your pyenv or venv and don't have a version of dbt globally installed.
-  * You no longer need to use the `dbt deps` command. Previously, you had to run that command.
+   * You don't have to run the `dbt deps` command when your environment starts. Previously, you had to do it during initialization. However, you'll still need to run `dbt deps` if you make changes to your `packages.yml` file.
 
 </TabItem>
 
@@ -109,7 +106,7 @@ Note that if you are using VS Code, you must restart it to pick up modified envi
 :::
 
 3. Verify the installation by running `./dbt --help` from the command line. If the help text doesn't indicate that you're using the dbt Cloud CLI, make sure you've deactivated your pyenv or venv and don't have a version of dbt globally installed.
-  * You no longer need to use the `dbt deps` command. Previously, you had to run that command.
+   * You don't have to run the `dbt deps` command when your environment starts. Previously, you had to do it during initialization. However, you'll still need to run `dbt deps` if you make changes to your `packages.yml` file.
 
 </TabItem>
 
@@ -121,10 +118,10 @@ Refer to the [FAQs](#faqs) if your operating system runs into path conflicts.
 
 2. Extract the `dbt-cloud-cli` binary to the same folder as your dbt project.
 
-```bash
-tar -xf dbt_0.29.9_linux_amd64.tar.gz
-./dbt --version
-```
+  ```bash
+  tar -xf dbt_0.29.9_linux_amd64.tar.gz
+  ./dbt --version
+  ```
 
 :::info
 
@@ -133,7 +130,7 @@ Advanced users can configure multiple projects to use the same Cloud CLI executa
 :::
 
 3. Verify the installation by running `./dbt --help` from the command line. If the help text doesn't indicate that you're using the dbt Cloud CLI, make sure you've deactivated your pyenv or venv and don't have a version of dbt globally installed.
-  * You no longer need to use the `dbt deps` command. Previously, you had to run that command.
+   * You don't have to run the `dbt deps` command when your environment starts. Previously, you had to do it during initialization. However, you'll still need to run `dbt deps` if you make changes to your `packages.yml` file.
 
 </TabItem>
 
@@ -142,15 +139,18 @@ Advanced users can configure multiple projects to use the same Cloud CLI executa
 
 ## 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.
+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.
 
-<Tabs>
 
+<Tabs>
 <TabItem value="existing" label="Existing dbt Core users (pip)">
 
 To update, run `pip install --upgrade dbt`.
 
+</TabItem>
+
 <TabItem value="mac" label="macOS (brew)">
 
 To update the dbt Cloud CLI, run `brew upgrade dbt-cloud-cli`. 
@@ -159,7 +159,7 @@ To update the dbt Cloud CLI, run `brew upgrade dbt-cloud-cli`.
 
 <TabItem value="windowslinux" label="Windows and Linux (executable)">
 
-To update, follow the same process explained in [Install manually (Windows)](/docs/cloud/cloud-cli-installation?install=windows#install-dbt-cloud-cli) and replace the existing `dbt.exe` executable with the new one.
+To update, follow the same process explained in [Windows](/docs/cloud/cloud-cli-installation?install=windows#install-dbt-cloud-cli) and replace the existing `dbt.exe` executable with the new one.
 
 </TabItem>
 
@@ -170,10 +170,9 @@ To update, follow the same process explained in [Install manually (Windows)](/do
 
 After installation, you can [configure](/docs/cloud/configure-cloud-cli) the dbt Cloud CLI for your dbt Cloud project and use it to run [dbt commands](/reference/dbt-commands) similar to dbt Core. For example, you can execute the following commands to compile a project using dbt Cloud:
 
-
-```bash
-dbt compile
-```
+  ```bash
+  dbt compile
+  ```
 
 ## FAQs
 
@@ -185,8 +184,8 @@ The dbt Cloud CLI and <a href="https://github.com/dbt-labs/dbt-core">dbt Core</a
 </details>
 
 <details>
-<summary>How do I run both the Cloud CLI and dbt Core?</summary>
-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).
+<summary>How do I run both the dbt Cloud CLI and dbt Core?</summary>
+For compatibility, both the dbt Cloud CLI and dbt Core are invoked by running <code>dbt</code>. 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:
 
@@ -196,7 +195,5 @@ If you have dbt Core installed locally, either:
 
 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 Cloud CLI to return to using dbt Core.
+You can always uninstall the dbt Cloud CLI to return to using dbt Core.
 </details>
-
-
diff --git a/website/docs/docs/cloud/configure-cloud-cli.md b/website/docs/docs/cloud/configure-cloud-cli.md
@@ -3,13 +3,12 @@ title: Configure dbt Cloud CLI
 id: configure-cloud-cli
 description: "Instructions on how to configure the dbt Cloud CLI"
 sidebar_label: "Configure dbt Cloud CLI"
+pagination_next: null
 ---
 
-:::info Public preview functionality
+import CloudCLIFlag from '/snippets/_cloud-cli-flag.md';
 
-The dbt Cloud CLI is currently in [public preview](/docs/dbt-versions/product-lifecycles#dbt-cloud). Share feedback or request features you'd like to see on the [dbt community Slack](https://getdbt.slack.com/archives/C05M77P54FL).
-
-::: 
+<CloudCLIFlag/>
 
 
 ## Prerequisites
@@ -26,34 +25,55 @@ Once you install the dbt Cloud CLI, you need to configure it to connect to a dbt
 
 1. Ensure you meet the prerequisites above.
 
-2. Download your credentials from dbt Cloud. Find the "Try the Cloud CLI" banner on the dbt homepage and click on it. Follow the instructions, downloading the config file to `~/.dbt/dbt_cloud.yml`.
+2. Download your credentials from dbt Cloud by clicking on the **Try the dbt Cloud CLI** banner on the dbt Cloud homepage.
+3. Follow the banner instructions and download the config file to `~/.dbt/dbt_cloud.yml`. The config file looks like:
+
+    ```yaml
+    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. Navigate to a dbt project in your terminal:
+    ```
 
-```bash
-cd ~/dbt-projects/jaffle_shop
-```
+4. After downloading the config file, navigate to a dbt project in your terminal:
 
-4. In your `dbt_project.yml` file, ensure there is a section titled `dbt-cloud`. This section is required to have a `project-id` field with the dbt-cloud project ID that you'd like to use. 
+    ```bash
+    cd ~/dbt-projects/jaffle_shop
+    ```
 
-```yaml
-# dbt_project.yml
-name:
+5. 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.
 
-version:
-...
+    ```yaml
+    # dbt_project.yml
+    name:
 
-dbt-cloud: 
-    project-id: PROJECT_ID
-```
+    version:
+    ...
 
-- To find your project ID, select **Develop** in the dbt Cloud navigation menu. You can use this URL to find the project ID. For example, in `https://cloud.getdbt.com/develop/26228/projects123456`, the project ID is `123456`.
+    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`.
 
 ## Use the dbt Cloud CLI
 
-The dbt Cloud CLI shares the same set of commands as dbt Core. dbt Cloud processes the dbt commands you invoke. 
+- The dbt Cloud CLI shares the same set of commands as dbt Core and processes the dbt commands you invoke. 
+- It allows you to use automatic deferral of build artifacts to your Cloud project's production environment.
+- It also supports [project dependencies](/docs/collaborate/govern/project-dependencies), which allows you to depend on another project using the metadata service in dbt Cloud. 
+  - Project dependencies instantly connects to and references (or  `ref`) public models defined in other projects. This means you don't need to execute or analyze these upstream models yourself. Instead, you treat them as an API that returns a dataset.
 
-The dbt Cloud CLI supports [project dependencies](/docs/collaborate/govern/project-dependencies), which is an exciting way to depend on another project using the metadata service in dbt Cloud. It instantly resolves references (or  `ref`) to 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.
 
-Share feedback or request features you'd like to see on the [dbt community Slack](https://getdbt.slack.com/archives/C05M77P54FL).
+:::infoShare feedback
+Share feedback or request features you'd like to see in the [dbt community Slack](https://getdbt.slack.com/archives/C05M77P54FL).
+:::
diff --git a/website/docs/reference/dbt-commands.md b/website/docs/reference/dbt-commands.md
@@ -4,7 +4,7 @@ title: "dbt Command reference"
 
 You can run dbt using the following tools:
 
-- In you browser with the [dbt Cloud IDE](/docs/cloud/dbt-cloud-ide/develop-in-the-cloud) 
+- In your browser with the [dbt Cloud IDE](/docs/cloud/dbt-cloud-ide/develop-in-the-cloud) 
 - On the command line interface using the [dbt Cloud CLI](/docs/cloud/cloud-cli-installation) or open-source [dbt Core](https://github.com/dbt-labs/dbt-core), both of which enable you to execute dbt commands. The key distinction is the dbt Cloud CLI is tailored for dbt Cloud's infrastructure and integrates with all its [features](/docs/cloud/about-cloud/dbt-cloud-features).
 
 The following sections outline the commands supported by dbt and their relevant flags. For information about selecting models on the command line, consult the docs on [Model selection syntax](/reference/node-selection/syntax).

diff --git a/website/snippets/_cloud-cli-flag.md b/website/snippets/_cloud-cli-flag.md
@@ -0,0 +1,5 @@
+:::info Public preview functionality
+
+The dbt Cloud CLI is currently in [public preview](/docs/dbt-versions/product-lifecycles#dbt-cloud). Share feedback or request features you'd like to see on the [dbt community Slack](https://getdbt.slack.com/archives/C05M77P54FL).
+
+:::