add new dbt invocation command

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

@@ -325,4 +325,6 @@ 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>
+
+<FAQ path="Troubleshooting/long-sessions-cloud-cli" />

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

@@ -154,6 +154,7 @@ When running `dbt sqlfluff` from the dbt Cloud CLI, the following are important
 - An SQLFluff command will return an exit code of 0 if it ran with any file violations. This dbt behavior differs from SQLFluff behavior, where a linting violation returns a non-zero exit code. dbt Labs plans on addressing this in a later release.
 
 ## FAQs
+
 <Expandable alt_header="How to create a .dbt directory and move your file">
 
 If you've never had a `.dbt` directory, you should perform the following recommended steps to create one. If you already have a `.dbt` directory, move the `dbt_cloud.yml` file into it.
@@ -201,5 +202,6 @@ This command moves the `dbt_cloud.yml` from the `Downloads` folder to the `.dbt`
 
 By default, [all artifacts](/reference/artifacts/dbt-artifacts) are downloaded when you execute dbt commands from the dbt Cloud CLI. To skip these files from being downloaded, add `--download-artifacts=false` to the command you want to run. This can help improve run-time performance but might break workflows that depend on assets like the [manifest](/reference/artifacts/manifest-json). 
 
-
 </Expandable>
+
+<FAQ path="Troubleshooting/long-sessions-cloud-cli" />

website/docs/faqs/Troubleshooting/long-sessions-cloud-cli.md

@@ -0,0 +1,12 @@
+---
+title: "I'm getting a \"Session occupied\" error in dbt Cloud CLI?"
+description: "How to debug long-running sessions in dbt Cloud CLI"
+sidebar_label: 'Debug long-running sessions in dbt Cloud CLI'
+id: long-sessions-cloud-cli
+---
+
+If you're receiving a `Session occupied` error in the dbt Cloud CLI or if you're experiencing a long-running session, you can use the `dbt invocation list` command in a separate terminal window to view the status of your active session. This helps you identify the model that's causing the long-running session and debug the issue.
+
+To cancel an active session, use the `Ctrl + Z` shortcut.
+
+To learn more about the `dbt invocation` command, see the [dbt invocation command reference](/reference/commands/invocation).

website/docs/reference/commands/invocation.md

@@ -0,0 +1,92 @@
+---
+title: "About dbt invocation command"
+sidebar_label: "invocation"
+id: invocation
+---
+
+The `dbt invocation` command is available in the [dbt Cloud CLI](/docs/cloud/cloud-cli-installation) and allows you to:
+- List active invocations to debug long-running or hanging sessions.
+- Identify and investigate sessions causing the `Session occupied` error.
+- Monitor currently active dbt commands (like `run`, `build`) in real-time.
+
+The `dbt invocation` command only lists _active invocations_. If no sessions are running, the list will be empty. Completed sessions aren't included in the output.
+
+## Usage
+
+This page lists the command and flag you can use with `dbt invocation`. To use them, add a command or option like this: `dbt invocation [flag]`.
+
+Available flags in the command line interface (CLI) are [`help`](#dbt-invocation-help) and [`list`](#dbt-invocation-list).
+
+### dbt invocation help
+
+The `help` command provides you with the help output for the `invocation` command in the CLI, including the available flags.
+
+```shell
+dbt invocation help
+```
+
+or
+
+```shell
+dbt help invocation
+```
+
+The command returns the following information:
+
+```bash
+dbt invocation help
+Manage invocations
+
+Usage:
+  dbt invocation [command]
+
+Available Commands:
+  list        List active invocations
+
+Flags:
+  -h, --help   help for invocation
+
+Global Flags:
+      --log-format LogFormat   The log format, either json or plain. (default plain)
+      --log-level LogLevel     The log level, one of debug, info, warning, error or fatal. (default info)
+      --no-color               Disables colorization of the output.
+  -q, --quiet                  Suppress all non-error logging to stdout.
+
+Use "dbt invocation [command] --help" for more information about a command.
+```
+
+### dbt invocation list
+
+The `list` command provides you with a list of active invocations in your dbt Cloud CLI. When a long-running session is active, you can use this command in a separate terminal window to view the active session to help debug the issue.
+
+```shell
+dbt invocation list
+```
+
+The command returns the following information, including the `ID`, `status`, `type`, `arguments`, and `started at` time of the active session:
+
+```bash
+dbt invocation list
+
+Active Invocations:
+  ID                             6dcf4723-e057-48b5-946f-a4d87e1d117a
+  Status                         running
+  Type                           cli
+  Args                           [run --select test.sql]
+  Started At                     2025-01-24 11:03:19
+
+➜  jaffle-shop git:(test-cli) ✗ 
+```
+
+:::tip
+
+To cancel an active session in the terminal, use the `Ctrl + Z` shortcut.
+
+:::
+
+## Related docs
+
+- [Install dbt Cloud CLI](/docs/cloud/cloud-cli-installation)
+- [Troubleshooting dbt Cloud CLI 'Session occupied' error](/faqs/Troubleshooting/long-sessions-cloud-cli)
+
+

website/docs/reference/dbt-commands.md

@@ -45,6 +45,7 @@ Commands with a ('❌') indicate write commands, commands with a ('✅') indicat
 | [environment](/reference/commands/dbt-environment) | Enables you to interact with your dbt Cloud environment. |   N/A | dbt Cloud CLI <br /> Requires [dbt v1.5 or higher](/docs/dbt-versions/core) |
 | help | Displays help information for any command | N/A | dbt Core, dbt Cloud CLI <br /> All [supported versions](/docs/dbt-versions/core) |
 | [init](/reference/commands/init) | Initializes a new dbt project |   ✅ | dbt Core<br /> All [supported versions](/docs/dbt-versions/core) |
+| [invocation](/reference/commands/invocation) | Enables users to debug long-running sessions by interacting with active invocations.|  N/    A | dbt Cloud CLI<br /> All [supported versions](/docs/dbt-versions/core) |
 | [list](/reference/commands/list) | Lists resources defined in a dbt project |  ✅ | All tools <br /> All [supported versions](/docs/dbt-versions/core) |
 | [parse](/reference/commands/parse) | Parses a project and writes detailed timing info |  ✅ | All tools <br /> All [supported versions](/docs/dbt-versions/core) |
 | reattach | Reattaches to the most recent invocation to retrieve logs and artifacts. |   N/A | dbt Cloud CLI <br /> Requires [dbt v1.6 or higher](/docs/dbt-versions/core) |

website/sidebars.js

@@ -1074,6 +1074,7 @@ const sidebarSettings = {
             "reference/commands/deps",
             "reference/commands/dbt-environment",
             "reference/commands/init",
+            "reference/commands/invocation",
             "reference/commands/list",
             "reference/commands/parse",
             "reference/commands/retry",