> ## Documentation Index
> Fetch the complete documentation index at: https://www.checklyhq.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# checkly rca

> Trigger and retrieve AI-powered root cause analyses for error groups.

> [!NOTE]
>
> Available since CLI v7.8.0.

The `checkly rca` command lets you trigger and retrieve [AI-powered root cause analyses (RCA)](https://www.checklyhq.com/docs/resolve/ai-root-cause-analysis/overview.md) for error groups directly from the terminal. An RCA examines an error group and returns a classification, root cause explanation, user impact assessment, and suggested code fixes when available.

> **Prerequisites**
>
> Before using `checkly rca`, ensure you have:
>
> * Checkly CLI installed
> * Valid Checkly account authentication (run `npx checkly login` if needed)
> * A Checkly plan that includes root cause analysis
>
> For additional setup information, see [CLI overview](https://www.checklyhq.com/docs/cli/overview.md).

> [!TIP]
>
> Existing root cause analysis results are also available via [`checkly checks get`](https://www.checklyhq.com/docs/cli/checkly-checks/#checkly-checks-get). Use `checkly rca run` to trigger a new analysis for an error group that doesn't have one yet.

## Usage

```bash Terminal theme={null}
npx checkly rca <subcommand> [arguments] [options]
```

## Subcommands

| Subcommand | Description |
| - | - |
| `run` | Trigger a root cause analysis for a check or test session error group. |
| `get` | Retrieve a root cause analysis by ID. |

## `checkly rca run`

Trigger a new root cause analysis for a check or test session error group. The analysis runs asynchronously — use `--watch` to wait for the result in your terminal.

**Usage:**

```bash Terminal theme={null}
npx checkly rca run [options]
```

**Options:**

| Option | Required | Description |
| - | - | - |
| `--error-group, -e` | yes\* | The check error group ID to analyze. |
| `--test-session-error-group, -te` | yes\* | The test session error group ID to analyze. |
| `--user-context` | - | Extra context to pass into the root cause analysis. |
| `--watch, -w` | - | Wait for the analysis to complete and display the result. |
| `--output, -o` | - | Output format: `detail`, `json`, or `md`. Default: `detail`. |

\*Pass either `--error-group` or `--test-session-error-group`.

### Run Options

**--error-group, -e** `string`

The check error group ID to trigger the analysis for. You can find error group IDs in the output of [`checkly checks get`](https://www.checklyhq.com/docs/cli/checkly-checks) when viewing a check with errors.

**Usage:**

```bash Terminal theme={null}
npx checkly rca run --error-group=<error-group-id>
npx checkly rca run -e <error-group-id>
```

**--test-session-error-group, -te** `string`

> [!NOTE]
>
> Available since CLI v8.0.0.

The test session error group ID to trigger the analysis for. You can find these IDs in the output of [`checkly test-sessions get`](https://www.checklyhq.com/docs/cli/checkly-test-sessions).

**Usage:**

```bash Terminal theme={null}
npx checkly rca run --test-session-error-group=<error-group-id>
npx checkly rca run -te <error-group-id>
```

**--user-context** `string`

> [!NOTE]
>
> Available in CLI v8.5.0+.

Extra context to pass into the root cause analysis. Use this to add details the error group does not contain, such as recent deploy changes or known service incidents.

**Usage:**

```bash Terminal theme={null}
npx checkly rca run --error-group=<error-group-id> --user-context="Started after the checkout deploy"
```

**--watch, -w** `boolean` (default: false)

Wait for the analysis to complete and display the full result. Without this flag, the command returns immediately with the RCA ID and a pending status.

Only works with `--output detail`.

**Usage:**

```bash Terminal theme={null}
npx checkly rca run --error-group=<error-group-id> --watch
npx checkly rca run -e <error-group-id> -w
```

**--output, -o** `string` (default: detail)

Set the output format. Use `json` for programmatic access or `md` for markdown.

**Usage:**

```bash Terminal theme={null}
npx checkly rca run --error-group=<error-group-id> --output=json
npx checkly rca run -e <error-group-id> -o md
```

### Run Examples

```bash Terminal theme={null}
# Trigger an RCA and wait for the result
npx checkly rca run --error-group=err-abc-123 --watch

# Trigger an RCA without waiting
npx checkly rca run --error-group=err-abc-123

# Trigger an RCA for a test session error group
npx checkly rca run --test-session-error-group=err-abc-123

# Add extra context for the analysis
npx checkly rca run --error-group=err-abc-123 --user-context="Started after the checkout deploy"

# Get the result as JSON
npx checkly rca run --error-group=err-abc-123 --output=json
```

## `checkly rca get`

Retrieve an existing root cause analysis by its ID. If the analysis is still generating, use `--watch` to wait for completion.

**Usage:**

```bash Terminal theme={null}
npx checkly rca get <id> [options]
```

**Arguments:**

| Argument | Description |
| - | - |
| `id` | The RCA ID to retrieve. |

**Options:**

| Option | Required | Description |
| - | - | - |
| `--watch, -w` | - | Wait for the analysis to complete if still generating. |
| `--output, -o` | - | Output format: `detail`, `json`, or `md`. Default: `detail`. |

### Get Options

**--watch, -w** `boolean` (default: false)

Wait for the analysis to complete if it is still generating. Without this flag, the command returns the current status immediately.

Only works with `--output detail`.

**Usage:**

```bash Terminal theme={null}
npx checkly rca get <id> --watch
npx checkly rca get <id> -w
```

**--output, -o** `string` (default: detail)

Set the output format. Use `json` for programmatic access or `md` for markdown.

**Usage:**

```bash Terminal theme={null}
npx checkly rca get <id> --output=json
npx checkly rca get <id> -o md
```

### Get Examples

```bash Terminal theme={null}
# Retrieve a completed RCA
npx checkly rca get rca-xyz-789

# Wait for a pending RCA to complete
npx checkly rca get rca-xyz-789 --watch

# Get the result as JSON
npx checkly rca get rca-xyz-789 --output=json
```

## RCA Output

A completed root cause analysis includes:

* **Classification** — the category of the error
* **Root cause** — explanation of what caused the error
* **User impact** — how the error affects end users
* **Code fix** — suggested fix when available
* **Evidence** — supporting artifacts from the analysis
* **Reference links** — relevant external resources

## Related Commands

* [`checkly checks`](https://www.checklyhq.com/docs/cli/checkly-checks) - List, inspect, and analyze checks (includes error groups)
* [`checkly test-sessions`](https://www.checklyhq.com/docs/cli/checkly-test-sessions) - Inspect recorded test sessions and test session error groups


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.