diff --git a/cli/checkly-init.mdx b/cli/checkly-init.mdx
new file mode 100644
index 00000000..da36ace5
--- /dev/null
+++ b/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'
+---
+
+Available since CLI v7.8.0.
+
+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.
+
+
+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.
+
+
+## Usage
+
+```bash Terminal
+npx checkly init [options]
+```
+
+| Option | Required | Description |
+|--------|----------|-------------|
+| `--target, -t` | - | Install the Checkly skill for a specific AI agent platform. |
+
+## Command Options
+
+
+
+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
+```
+
+
+
+## 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
+
+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.
+
+### 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
diff --git a/cli/checkly-pw-test.mdx b/cli/checkly-pw-test.mdx
index b4e47592..c3c87253 100644
--- a/cli/checkly-pw-test.mdx
+++ b/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"
+
+
+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
+```
+
+
+
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.
diff --git a/cli/checkly-rca.mdx b/cli/checkly-rca.mdx
new file mode 100644
index 00000000..c5332122
--- /dev/null
+++ b/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'
+---
+
+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](/cli/overview).
+
+
+## Usage
+
+```bash Terminal
+npx checkly rca [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
+
+
+
+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=
+npx checkly rca run -e
+```
+
+
+
+
+
+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= --watch
+npx checkly rca run -e -w
+```
+
+
+
+
+
+Set the output format. Use `json` for programmatic access or `md` for markdown.
+
+**Usage:**
+
+```bash Terminal
+npx checkly rca run --error-group= --output=json
+npx checkly rca run -e -o md
+```
+
+
+
+### 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 [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
+
+
+
+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 --watch
+npx checkly rca get -w
+```
+
+
+
+
+
+Set the output format. Use `json` for programmatic access or `md` for markdown.
+
+**Usage:**
+
+```bash Terminal
+npx checkly rca get --output=json
+npx checkly rca get -o md
+```
+
+
+
+### 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)
diff --git a/cli/checkly-test.mdx b/cli/checkly-test.mdx
index a67c4534..fba18127 100644
--- a/cli/checkly-test.mdx
+++ b/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"
+
+
+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
+```
+
+
+
How many times to retry a failing test run. Default: 0, max: 3
diff --git a/cli/checkly-trigger.mdx b/cli/checkly-trigger.mdx
index 2510611a..24080d74 100644
--- a/cli/checkly-trigger.mdx
+++ b/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.
+
+
+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
+```
+
+
+
How many times to retry a failed check run.
diff --git a/cli/installation.mdx b/cli/installation.mdx
index e48fdc2f..dc283fd8 100644
--- a/cli/installation.mdx
+++ b/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
diff --git a/cli/overview.mdx b/cli/overview.mdx
index c26b8d69..770ef86d 100644
--- a/cli/overview.mdx
+++ b/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.
diff --git a/detect/testing/creating-your-first-test.mdx b/detect/testing/creating-your-first-test.mdx
index 8e65610a..0d0192db 100644
--- a/detect/testing/creating-your-first-test.mdx
+++ b/detect/testing/creating-your-first-test.mdx
@@ -20,7 +20,7 @@ Checkly enables you to transform your existing Playwright tests into powerful sy
Start by creating a new Checkly project using the CLI:
```bash Terminal
-npm create checkly@latest
+npx checkly init
```
This command will:
diff --git a/docs.json b/docs.json
index be8b912b..3de544b5 100644
--- a/docs.json
+++ b/docs.json
@@ -548,9 +548,11 @@
"cli/checkly-env",
"cli/checkly-import",
"cli/checkly-incidents",
+ "cli/checkly-init",
"cli/checkly-login",
"cli/checkly-logout",
"cli/checkly-pw-test",
+ "cli/checkly-rca",
"cli/checkly-runtimes",
"cli/checkly-skills",
"cli/checkly-status-pages",
diff --git a/guides/agentic-workflows.mdx b/guides/agentic-workflows.mdx
index 1eb42bc3..71e4a51a 100644
--- a/guides/agentic-workflows.mdx
+++ b/guides/agentic-workflows.mdx
@@ -66,7 +66,7 @@ If your project doesn't include a valid `checkly.config.ts` yet, ask your AI ass
I want to monitor this site with Checkly. Can you create a new base setup using the CLI?
```
-The agent will then run `npm create checkly`, which generates a `checkly.config.ts` file and a `__checks__` directory. This base configuration file defines your project meta information, default check frequencies, and monitoring locations.
+The agent will then run `npx checkly init`, which generates a `checkly.config.ts` file and a `__checks__` directory. This base configuration file defines your project meta information, default check frequencies, and monitoring locations.
```ts checkly.config.ts
import { defineConfig } from 'checkly'
diff --git a/guides/claude-code-monitoring.mdx b/guides/claude-code-monitoring.mdx
index 06005134..622484b5 100644
--- a/guides/claude-code-monitoring.mdx
+++ b/guides/claude-code-monitoring.mdx
@@ -18,7 +18,7 @@ AI-assisted coding promises to massively upgrade developer productivity, and wit
If you haven't already, start by [installing the Checkly CLI](https://www.checklyhq.com/docs/cli/installation/), then create a repository that will be the 'project' that contains all your Checkly monitors managed as code. If you don't already have a project, create one with:
```bash
-npm create checkly@latest
+npx checkly init
```
Next, install [Claude Code](https://www.anthropic.com/claude-code) globally with
diff --git a/guides/developer-fixtures.mdx b/guides/developer-fixtures.mdx
index 565bd2ec..4766111a 100644
--- a/guides/developer-fixtures.mdx
+++ b/guides/developer-fixtures.mdx
@@ -37,7 +37,7 @@ Though the rest of this guide will refer to our developer as the person we're en
First off, our developer may not be very excited to log into a web interface to create new monitors. Since developers are used to running and deploying code from the command line, we want to make available the Checkly CLI to our developers. A [full guide to the Checkly CLI](https://www.checklyhq.com/cli/overview) is on our documentation site, but in general the process would look like:
1. Set up the CLI on the developer's machine - install is easy with npm, then the developer can authenticate their cli with `npx checkly login`.
-2. Create a new project - developers can either grab an existing repository with the team's checks, or use `npm create checkly@latest` to make a new project.
+2. Create a new project - developers can either grab an existing repository with the team's checks, or use `npx checkly init` to make a new project.
3. Run your checks - rather than running new Playwright checks from the developer's laptop, they can run checks through the whole Checkly system with `npx checkly test`, the tool will scan the project for tests, run them as configured from the real geographic locations, and give a local report on results.
4. Deploy your checks - Once the developer is happy with their checks, they can deploy them with `npx checkly deploy`, and they'll show up for all users in the web interface.
diff --git a/guides/end-to-end-monitoring.mdx b/guides/end-to-end-monitoring.mdx
index c9957d66..4c7b88c5 100644
--- a/guides/end-to-end-monitoring.mdx
+++ b/guides/end-to-end-monitoring.mdx
@@ -233,7 +233,7 @@ Step 1: Setting Up a Checkly Account
Ensure you have an active Checkly account. If not, sign up. The default free Team trial lasts for 14 days. To access advanced features beyond the trial, subscribe to a pricing plan based on your needs.
Step 2: Setting Up Checkly in Repository
After completing the installation steps, open a terminal in the directory of your project and run the following command:
-`npm create checkly@latest`
+`npx checkly init`
This command will bootstrap your repository with the basics needed to start using Checkly MaC in your project.
diff --git a/guides/getting-started-with-monitoring-as-code.mdx b/guides/getting-started-with-monitoring-as-code.mdx
index 4f3c5674..45e81fda 100644
--- a/guides/getting-started-with-monitoring-as-code.mdx
+++ b/guides/getting-started-with-monitoring-as-code.mdx
@@ -36,7 +36,7 @@ Let's jump into the step-by-step process.
We’re going to pretend we are working on adding a feature to a web application that also requires some updates to our API backend. We will assume we already bootstrapped our repository with a Checkly CLI project using:
```bash install-checkly-cli
-npm create checkly@latest
+npx checkly init
```
This command sets up all the basics to kickstart your MaC workflow in your repo.
diff --git a/guides/startup-guide-detect-communicate-resolve.mdx b/guides/startup-guide-detect-communicate-resolve.mdx
index 80823bbc..f57023c6 100644
--- a/guides/startup-guide-detect-communicate-resolve.mdx
+++ b/guides/startup-guide-detect-communicate-resolve.mdx
@@ -43,7 +43,7 @@ This section will guide you through:
Start by creating a new project with:
```bash
-npm create checkly@latest
+npx checkly init
```
You’ll get a few quick prompts on the name and setup of your project:
diff --git a/snippets/cli-project-init.mdx b/snippets/cli-project-init.mdx
index 648de32d..ab1bfcf7 100644
--- a/snippets/cli-project-init.mdx
+++ b/snippets/cli-project-init.mdx
@@ -1,3 +1,3 @@
```bash Terminal
-npm create checkly@latest
+npx checkly init
```
\ No newline at end of file