Skip to main content
Available since CLI v7.8.0.
The checkly rca command lets you trigger and retrieve AI-powered root cause analyses (RCA) 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.
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.

​
Usage

Terminal
npx checkly rca <subcommand> [arguments] [options]

​
Subcommands

SubcommandDescription
runTrigger a root cause analysis for an error group.
getRetrieve a root cause analysis by ID.

​
checkly rca run

Trigger a new root cause analysis for an error group. The analysis runs asynchronously — use --watch to wait for the result in your terminal. Usage:
Terminal
npx checkly rca run [options]
Options:
OptionRequiredDescription
--error-group, -eyesThe error group ID to analyze.
--watch, -w-Wait for the analysis to complete and display the result.
--output, -o-Output format: detail, json, or md. Default: detail.

​
Run Options

​
--error-group, -e
string
The error group ID to trigger the analysis for. You can find error group IDs in the output of checkly checks get when viewing a check with errors.Usage:
Terminal
npx checkly rca run --error-group=<error-group-id>
npx checkly rca run -e <error-group-id>
​
--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:
Terminal
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:
Terminal
npx checkly rca run --error-group=<error-group-id> --output=json
npx checkly rca run -e <error-group-id> -o md

​
Run Examples

Terminal
# 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

# 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:
Terminal
npx checkly rca get <id> [options]
Arguments:
ArgumentDescription
idThe RCA ID to retrieve.
Options:
OptionRequiredDescription
--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:
Terminal
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:
Terminal
npx checkly rca get <id> --output=json
npx checkly rca get <id> -o md

​
Get Examples

Terminal
# 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
  • checkly checks - List, inspect, and analyze checks (includes error groups)