Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

add cloud cli video and alias info #4320

Merged
merged 22 commits into from
Oct 25, 2023
Merged
Changes from 6 commits
Commits
Show all changes
22 commits
Select commit Hold shift + click to select a range
953d748
adding steve's video
mirnawong1 Oct 24, 2023
a3894dc
Update website/docs/docs/cloud/cloud-cli-installation.md
mirnawong1 Oct 24, 2023
968b19b
Merge branch 'current' into mwong-add-cloud-cli-loom
mirnawong1 Oct 24, 2023
640e758
Update website/docs/docs/cloud/cloud-cli-installation.md
mirnawong1 Oct 24, 2023
2228037
Update website/docs/docs/cloud/cloud-cli-installation.md
mirnawong1 Oct 24, 2023
c8e066a
Update website/docs/docs/cloud/cloud-cli-installation.md
mirnawong1 Oct 24, 2023
9f814f9
Merge branch 'current' into mwong-add-cloud-cli-loom
matthewshaver Oct 24, 2023
7656855
Update cloud-cli-installation.md
mirnawong1 Oct 25, 2023
f58614c
Update cloud-cli-installation.md
mirnawong1 Oct 25, 2023
c3f50c9
rephrase
mirnawong1 Oct 25, 2023
5c8e41e
Merge branch 'current' into mwong-add-cloud-cli-loom
mirnawong1 Oct 25, 2023
7bd3568
fold in feedback
mirnawong1 Oct 25, 2023
cd98958
Merge branch 'mwong-add-cloud-cli-loom' of https://github.com/dbt-lab…
mirnawong1 Oct 25, 2023
7a38dbd
Update website/docs/docs/cloud/cloud-cli-installation.md
mirnawong1 Oct 25, 2023
3ca3da3
add colon
mirnawong1 Oct 25, 2023
2aa518b
Merge branch 'mwong-add-cloud-cli-loom' of https://github.com/dbt-lab…
mirnawong1 Oct 25, 2023
4868ae8
Merge branch 'current' into mwong-add-cloud-cli-loom
mirnawong1 Oct 25, 2023
736868a
Update cloud-cli-installation.md
mirnawong1 Oct 25, 2023
54f5b14
tweak video callout
mirnawong1 Oct 25, 2023
6590e98
Merge branch 'current' into mwong-add-cloud-cli-loom
mirnawong1 Oct 25, 2023
504090f
Update website/docs/docs/cloud/cloud-cli-installation.md
mirnawong1 Oct 25, 2023
39231c9
Merge branch 'current' into mwong-add-cloud-cli-loom
mirnawong1 Oct 25, 2023
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
80 changes: 54 additions & 26 deletions website/docs/docs/cloud/cloud-cli-installation.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ You must be on dbt version 1.5 or higher. Refer to [dbt Cloud versions](/docs/db

## Install dbt Cloud CLI

You can install the dbt Cloud CLI on the command line by using one of these methods:
You can install the dbt Cloud CLI on the command line by using one of these methods. For a step-by-step video guide, refer to the [FAQs](#faqs).

<Tabs queryString="install">

Expand All @@ -38,24 +38,35 @@ You can install the dbt Cloud CLI on the command line by using one of these meth
Before you begin, make sure you have [Homebrew installed](http://brew.sh/) in your code editor or command line terminal. Refer to the [FAQs](#faqs) if your operating system runs into path conflicts.


1. Run the following command to verify that there is no conflict with a dbt Core installation on your system:
1. Run the following command to verify that you don't already have dbt Core installed:

```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.
- This should return a `dbt not found`. If the dbt help text appears, use `pip uninstall dbt` to remove dbt Core from your machine. <br />

2. Install the dbt Cloud CLI with Homebrew:

```bash
brew untap dbt-labs/dbt
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.
- First, remove the dbt-labs tap, the separate repository for packages, from Homebrew. This prevents Homebrew from installing packages from that repository:
```bash
brew untap dbt-labs/dbt
- Then run `brew tap` to add and install the dbt Cloud CLI as a package:
```bash
brew tap dbt-labs/dbt-cli
```
- Lastly, install the dbt Cloud CLI with Homebrew:
```bash
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 global dbt version installed.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we drop some sample text of what the expected output is?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

i thought about it and opted to leave it out because dbt --help returns a pretty long output (basically it gives users all the flags/commands they can use) so i decided to leave it out and thought that the 'help text...' would be clear enough

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"dbt --help returns a pretty long output.." is the text that indicates it is successfully running for cloud going to be immediately apparent in this output or will they have to dig for it? Maybe including just a sample of what to look for so they know 100% it was successful?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think I'm maybe just confused by what this sentence is saying. Are we saying that the ability to run dbt --help is enough to confirm installation, or are they supposed to see something that specifically states it's the Cloud CLI and not the Core CLI? If it's the former, maybe we can clarify it by saying something like: "If the installation was successful, executing dbt --help will produce a list of commands available to run."

Copy link
Contributor Author

@mirnawong1 mirnawong1 Oct 25, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ok maybe this clarifies it further?

Screenshot 2023-10-25 at 10 39 43

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

4. After you've verified the installation, [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, execute `dbt compile` to compile a project using dbt Cloud and validate your models and tests.

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`](/docs/core/connect-data-platform/profiles.yml) file locally on your machine.

</TabItem>

<TabItem value="windows" label="Windows (native executable)">
Expand All @@ -73,9 +84,14 @@ Advanced users can configure multiple projects to use the same dbt Cloud CLI by
Note that if you are using VS Code, you must restart it to pick up modified environment variables.
:::

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

4. After installation, [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, execute `dbt compile`, to compile a project using dbt Cloud and confirm that it works.
mirnawong1 marked this conversation as resolved.
Show resolved Hide resolved

**Note**, that 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`](/docs/core/connect-data-platform/profiles.yml) file.

</TabItem>

<TabItem value="linux" label="Linux (native executable)">
Expand All @@ -97,23 +113,32 @@ 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.
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 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.

4. After installation, [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, execute `dbt compile`, to compile a project using dbt Cloud and confirm that it works.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
4. After installation, [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, execute `dbt compile`, to compile a project using dbt Cloud and confirm that it works.
4. After you've verified the installation, [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, execute `dbt compile` to compile a project using dbt Cloud and validate your models and tests.


**Note**, that 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`](/docs/core/connect-data-platform/profiles.yml) file.
mirnawong1 marked this conversation as resolved.
Show resolved Hide resolved

</TabItem>

<TabItem value="pip" label="Existing dbt Core users (pip)">

:::info Use native packages or a virtual environment to avoid overriding dbt Core

Installing the dbt Cloud CLI with pip replaces dbt Core. This change can be avoided by using the native install method and configuring your PATH or by creating a new virtual environment.
:::info Use native packages or a virtual environment to prevent dbt Core conflicts

Otherwise, to switch back to dbt Core, uninstall the dbt Cloud CLI and follow the dbt Core installation instructions.
To prevent overwriting dbt Core, avoid installing the dbt Cloud CLI with pip. Instead, consider using the native installation method and configuring your PATH or create a new virtual environment.

If you've already installed the dbt Cloud CLI and need to switch back to dbt Core, uninstall the dbt Cloud CLI, and follow the dbt Core installation instructions.

You can also have both dbt Cloud CLI and dbt Core installed simultaneously. To avoid conflicts, alias the dbt Cloud CLI as `dbt-cloud`. For more details, check the [FAQs](#faqs) if your operating system experiences path conflicts.
:::

:::

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-dbt-cloud-cli-in-pip).


### Install a virtual environment

We recommend using virtual environments (venv) to namespace `cloud-cli`.
Expand Down Expand Up @@ -156,6 +181,10 @@ We recommend using virtual environments (venv) to namespace `cloud-cli`.
pip3 install dbt-core==VERSION
```

4. After installation, [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, execute `dbt compile`, to compile a project using dbt Cloud and confirm that it works.
mirnawong1 marked this conversation as resolved.
Show resolved Hide resolved

**Note**, that 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`](/docs/core/connect-data-platform/profiles.yml) file.
mirnawong1 marked this conversation as resolved.
Show resolved Hide resolved

</TabItem>

</Tabs>
Expand Down Expand Up @@ -198,16 +227,6 @@ To update:

</Tabs>


## Next steps

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 `dbt compile` to compile a project using dbt Cloud.

Note, that 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`](/docs/core/connect-data-platform/profiles.yml) file.


## FAQs

<details>
Expand All @@ -231,3 +250,12 @@ If you have dbt Core installed locally, either:

You can always uninstall the dbt Cloud CLI to return to using dbt Core.
</details>

<details>
<summary>Are there any instructional videos to help guide me through installation? </summary>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not opposed to this being in the FAQs, but given what we know about scroll rates, this might get more views if we embed it directly into the instructions above, rather than/in addition to putting it here.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yea i also tried adding it in the install header but then it took up too much of the page before introducing the install steps. I could link to it but that also means it'll navigate the user to another tab (and away from the docs). Which is why i figured the faq and a link to the faq was a smoother experience (as opposed to navigating them away from the docs)

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'll ask if we can get pop out windows for videos

For a video walkthrough of the installation process, refer to the following video:

<LoomVideo id="dd80828306c5432a996d4580135041b6?sid=fe1895b7-1281-4e42-9968-5f7d11768000"/>

</details>

Loading