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.
Existing root cause analysis results are also available via checkly checks get. Use checkly rca run to trigger a new analysis for an error group that doesn’t have one yet.

​
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)