docs: CLI 7.8.0 command documentation

cli/checkly-init.mdx

@@ -0,0 +1,108 @@
+---
+title: checkly init
+description: 'Initialize Checkly in your project with interactive or AI-assisted onboarding.'
+sidebarTitle: 'checkly init'
+---
+
+<Note>Available since CLI v7.8.0.</Note>
+
+The `checkly init` command sets up Checkly in your project. It detects your project's existing configuration — package.json, Playwright, and Checkly config files — and walks you through the setup accordingly.
+
+You can set up Checkly manually or let your AI coding agent handle the configuration. The command adapts its behavior based on the environment: interactive terminals get guided prompts, CI environments get non-interactive setup, and AI agents receive structured output.
+
+<Accordion title="Prerequisites">
+Before using `checkly init`, ensure you have:
+
+- Node.js installed
+- A project directory (an existing `package.json` is optional — the command can create one)
+
+No existing Checkly account or configuration is required.
+</Accordion>
+
+## Usage
+
+```bash Terminal
+npx checkly init [options]
+```
+
+| Option | Required | Description |
+|--------|----------|-------------|
+| `--target, -t` | - | Install the Checkly skill for a specific AI agent platform. |
+
+## Command Options
+
+<ResponseField name="--target, -t" type="string">
+
+Install the [Checkly agent skill](/ai/skills) for a specific AI agent platform. Available platforms: `claude`, `cursor`, `windsurf`, `github-copilot`, `gemini-cli`, `codex`, `amp`.
+
+**Usage:**
+
+```bash Terminal
+npx checkly init --target=claude
+npx checkly init -t cursor
+```
+
+</ResponseField>
+
+## What to Expect
+
+The `init` command detects your project context and adjusts its flow:
+
+- **No `package.json`** — prompts you to create one before continuing.
+- **No Checkly config** — creates a `checkly.config.ts` and installs `checkly` and `jiti` as dev dependencies.
+- **Playwright detected** — provides context-aware setup that accounts for your existing test infrastructure.
+- **Existing Checkly project** — refreshes your agent skill to the latest version.
+
+### AI-Assisted Setup
+
+When you choose the AI-assisted path (or pass `--target`), the command:
+
+1. Installs the [Checkly agent skill](/ai/skills) for your platform
+2. Creates a `checkly.config.ts` if one doesn't exist
+3. Installs dependencies
+4. Generates a starter prompt you can paste into your AI agent to begin configuring checks
+
+<Tip>The starter prompt gives your AI agent all the context it needs about your project and Checkly's capabilities. Copy it into your agent's chat to start creating checks.</Tip>
+
+### Manual Setup
+
+When you choose the manual path, the command:
+
+1. Creates a `checkly.config.ts` if one doesn't exist
+2. Installs dependencies
+3. Optionally copies example checks (API, browser, heartbeat, URL monitor) into a `__checks__` directory
+
+### CI Mode
+
+In CI environments (when `CI=true`), the command runs non-interactively and outputs setup instructions.
+
+```bash Terminal
+CI=true npx checkly init
+```
+
+## Examples
+
+```bash Terminal
+# Interactive setup
+npx checkly init
+
+# Set up with Claude Code agent skill
+npx checkly init --target=claude
+
+# Non-interactive CI setup
+CI=true npx checkly init
+```
+
+## Next Steps
+
+After initialization, the typical workflow is:
+
+1. **Log in** — `npx checkly login` to authenticate with your Checkly account
+2. **Test** — `npx checkly test --record` to dry-run your checks
+3. **Deploy** — `npx checkly deploy` to deploy checks to Checkly
+
+## Related Commands
+
+- [`checkly skills`](/cli/checkly-skills) - Print project context and install agent skills
+- [`checkly login`](/cli/checkly-login) - Log in to your Checkly account
+- [`checkly deploy`](/cli/checkly-deploy) - Deploy checks to Checkly

cli/checkly-pw-test.mdx

@@ -42,6 +42,7 @@ Define `checkly pw-test` specific options before the `--` separator:
 | `--location, -l` | - | The location to run the checks at. |
 | `--private-location` | - | The private location to run checks at. |
 | `--[no-]record` | - | Record test results in Checkly as a test session with full logs, traces and videos. |
+| `--refresh-cache` | - | Force a fresh install of dependencies and update the cached version. |
 | `--reporter` | - | One or more custom reporters for the test output. Supports comma-separated values and repeated flags. |
 | `--stream-logs` | - | Stream logs from the test run to the console. |
 | `--test-session-name` | - | A name to use when storing results in Checkly |
@@ -187,6 +188,18 @@ npx checkly pw-test --private-location="staging-vpc"
 
 </ResponseField>
 
+<ResponseField name="--refresh-cache" type="boolean" default="false">
+
+Force a fresh install of dependencies and update the cached version. Use this when you've changed your project's dependencies and need Checkly to pick up the latest versions instead of using the cache from a previous run.
+
+**Usage:**
+
+```bash Terminal
+npx checkly pw-test --refresh-cache
+```
+
+</ResponseField>
+
 <ResponseField name="--[no-]record" type="boolean">
 
 The `pw-test` automatically records your test results as a [test session](/detect/testing/overview) with full logs, traces, and videos. Use `--no-record` to disable recording.

cli/checkly-rca.mdx

@@ -0,0 +1,187 @@
+---
+title: checkly rca
+description: 'Trigger and retrieve AI-powered root cause analyses for error groups.'
+sidebarTitle: 'checkly rca'
+---
+
+<Note>Available since CLI v7.8.0.</Note>
+
+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.
+
+<Accordion title="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](/cli/overview).
+</Accordion>
+
+## Usage
+
+```bash Terminal
+npx checkly rca <subcommand> [arguments] [options]
+```
+
+## Subcommands
+
+| Subcommand | Description |
+|------------|-------------|
+| `run` | Trigger a root cause analysis for an error group. |
+| `get` | Retrieve 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:**
+
+```bash Terminal
+npx checkly rca run [options]
+```
+
+**Options:**
+
+| Option | Required | Description |
+|--------|----------|-------------|
+| `--error-group, -e` | yes | The 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
+
+<ResponseField name="--error-group, -e" type="string">
+
+The error group ID to trigger the analysis for. You can find error group IDs in the output of [`checkly checks get`](/cli/checkly-checks) when viewing a check with errors.
+
+**Usage:**
+
+```bash Terminal
+npx checkly rca run --error-group=<error-group-id>
+npx checkly rca run -e <error-group-id>
+```
+
+</ResponseField>
+
+<ResponseField name="--watch, -w" type="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
+npx checkly rca run --error-group=<error-group-id> --watch
+npx checkly rca run -e <error-group-id> -w
+```
+
+</ResponseField>
+
+<ResponseField name="--output, -o" type="string" default="detail">
+
+Set the output format. Use `json` for programmatic access or `md` for markdown.
+
+**Usage:**
+
+```bash Terminal
+npx checkly rca run --error-group=<error-group-id> --output=json
+npx checkly rca run -e <error-group-id> -o md
+```
+
+</ResponseField>
+
+### Run Examples
+
+```bash 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:**
+
+```bash Terminal
+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
+
+<ResponseField name="--watch, -w" type="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
+npx checkly rca get <id> --watch
+npx checkly rca get <id> -w
+```
+
+</ResponseField>
+
+<ResponseField name="--output, -o" type="string" default="detail">
+
+Set the output format. Use `json` for programmatic access or `md` for markdown.
+
+**Usage:**
+
+```bash Terminal
+npx checkly rca get <id> --output=json
+npx checkly rca get <id> -o md
+```
+
+</ResponseField>
+
+### Get Examples
+
+```bash 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
+
+## Related Commands
+
+- [`checkly checks`](/cli/checkly-checks) - List, inspect, and analyze checks (includes error groups)

cli/checkly-test.mdx

@@ -28,6 +28,7 @@ npx checkly test [arguments] [options]
 | `--location, -l` | - | The location to run the checks at. |
 | `--private-location` | - | The private location to run checks at. |
 | `--record` | - | Record test results in Checkly as a test session with full logs, traces and videos. |
+| `--refresh-cache` | - | Force a fresh install of dependencies and update the cached version. |
 | `--reporter, -r` | - | One or more custom reporters for the test output. Supports comma-separated values and repeated flags. |
 | `--retries` | - | How many times to retry a failing test run. |
 | `--tags, -t` | - | Filter the checks to be run using a comma separated list of tags. |
@@ -240,6 +241,18 @@ npx checkly test --record --test-session-name="CI Build #123"
 
 </ResponseField>
 
+<ResponseField name="--refresh-cache" type="boolean" default="false">
+
+Force a fresh install of dependencies and update the cached version. Use this when you've changed your project's dependencies and need Checkly to pick up the latest versions instead of using the cache from a previous run.
+
+**Usage:**
+
+```bash Terminal
+npx checkly test --refresh-cache
+```
+
+</ResponseField>
+
 <ResponseField name="--retries" type="number">
 
 How many times to retry a failing test run. Default: 0, max: 3

cli/checkly-trigger.mdx

@@ -27,6 +27,7 @@ npx checkly trigger [options]
 | `--location, -l` | - | The location to run the checks at. |
 | `--private-location` | - | The private location to run checks at. |
 | `--record` | - | Record check results in Checkly as a test session with full logs, traces and videos. |
+| `--refresh-cache` | - | Force a fresh install of dependencies and update the cached version. |
 | `--reporter, -r` | - | One or more custom reporters for the test output. Supports comma-separated values and repeated flags. |
 | `--retries` | - | How many times to retry a check run. |
 | `--tags, -t` | - | Filter the checks to be run using a comma separated list of tags. |
@@ -284,6 +285,18 @@ npx checkly trigger --record --tags critical
 Records provide full visibility including logs, traces, and videos for debugging failed checks.
 </ResponseField>
 
+<ResponseField name="--refresh-cache" type="boolean" default="false">
+
+Force a fresh install of dependencies and update the cached version. Use this when you've changed your project's dependencies and need Checkly to pick up the latest versions instead of using the cache from a previous run.
+
+**Usage:**
+
+```bash Terminal
+npx checkly trigger --refresh-cache
+```
+
+</ResponseField>
+
 <ResponseField name="--retries" type="number" default="0">
 
 How many times to retry a failed check run.

cli/installation.mdx

@@ -4,7 +4,7 @@ description: 'Creating a CLI project from scratch'
 sidebarTitle: 'Installation'
 ---
 
-To kickstart a new project with the CLI, we recommend running `npm create checkly@latest`. But you can also add the CLI
+To kickstart a new project with the CLI, we recommend running `npx checkly init`. But you can also add the CLI
 from scratch with the following steps.
 
 ## Prerequisites

cli/overview.mdx

@@ -16,7 +16,7 @@ Get started by installing the CLI using the following command which will guide y
 set up a fully working example.
 
 ```bash Terminal
-npm create checkly@latest
+npx checkly init
 ```
 
 Now, login to your Checkly account or sign up for a new account right from the terminal.