Update cloud-cli-installation.md

website/docs/docs/cloud/cloud-cli-installation.md

@@ -325,4 +325,10 @@ If you've ran a dbt command and receive a <code>Session occupied</code> error, y
 
 The Cloud CLI allows only one command that writes to the data warehouse at a time. If you attempt to run multiple write commands simultaneously (for example, `dbt run` and `dbt build`), you will encounter a `stuck session` error. To resolve this, cancel the specific invocation by passing its ID to the cancel command. For more information, refer to [parallel execution](/reference/dbt-commands#parallel-execution).
 
-</DetailsToggle>
+</DetailsToggle>
+
+## Limitations
+
+import CloudCliRelativePath from '/snippets/_cloud-cli-relative-path.md';
+
+<CloudCliRelativePath />

website/docs/docs/cloud/configure-cloud-cli.md

@@ -124,6 +124,12 @@ As a tip, most command-line tools have a `--help` flag to show available command
 - `dbt run --help`: Lists the flags available for the `run` command
 :::
 
+### Considerations
+
+import CloudCliRelativePath from '/snippets/_cloud-cli-relative-path.md';
+
+<CloudCliRelativePath />
+
 ### Lint SQL files 
 
 From the dbt Cloud CLI, you can invoke [SQLFluff](https://sqlfluff.com/) which is a modular and configurable SQL linter that warns you of complex functions, syntax, formatting, and compilation errors. Many of the same flags that you can pass to SQLFluff are available from the dbt Cloud CLI.

website/snippets/_cloud-cli-relative-path.md

@@ -0,0 +1,20 @@
+The dbt Cloud CLI doesn't currently support relative paths in the [`packages.yml` file](/docs/build/packages).
+
+For example, trying to install [a local package](/docs/build/packages#local-packages) (`shared_macros` directory) in your `packages.yml` file won't work:
+
+```yaml
+# repository_root/my_dbt_project_in_a_subdirectory/packages.yml
+
+packages:
+  - local: ../shared_macros
+```
+
+In this example, `../shared_macros` is a relative path that tells dbt to look for:
+- `..` — Go one directory up (to repository_root).
+- `/shared_macros` — Find the `shared_macros` folder in the root directory.
+
+To work around this limitation:
+- Use the [dbt Cloud IDE](/docs/cloud/dbt-cloud-ide/develop-in-the-cloud), which supports relative paths for this use case.
+- If using a monorepo with multiple projects as subdirectories, use [private packages](/docs/build/packages#private-packages) or the [git clone method](/docs/build/packages#ssh-key-method-command-line-only) to share package across projects.
+- If using a monorepo with multiple projects as separate repositories, use [project dependencies](/docs/collaborate/govern/project-dependencies) to share the package across projects.
+- If using monorepo with single project, store the package in the same repository as the project.