Skip to content

Commit fd81902

Browse files
thebiglabaskyclaude
thebiglabasky
and
claude
committed
docs: document CLI 7.8.0 commands and changes
Add documentation for new `checkly init` and `checkly rca` commands. Add `--refresh-cache` flag to `pw-test`, `test`, and `trigger` docs. Replace all `npm create checkly@latest` references with `npx checkly init`. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent a4ca127 commit fd81902

16 files changed

Lines changed: 346 additions & 10 deletions

‎cli/checkly-init.mdx‎

Lines changed: 108 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
1+
---
2+
title: checkly init
3+
description: 'Initialize Checkly in your project with interactive or AI-assisted onboarding.'
4+
sidebarTitle: 'checkly init'
5+
---
6+
7+
<Note>Available since CLI v7.8.0.</Note>
8+
9+
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.
10+
11+
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.
12+
13+
<Accordion title="Prerequisites">
14+
Before using `checkly init`, ensure you have:
15+
16+
- Node.js installed
17+
- A project directory (an existing `package.json` is optional — the command can create one)
18+
19+
No existing Checkly account or configuration is required.
20+
</Accordion>
21+
22+
## Usage
23+
24+
```bash Terminal
25+
npx checkly init [options]
26+
```
27+
28+
| Option | Required | Description |
29+
|--------|----------|-------------|
30+
| `--target, -t` | - | Install the Checkly skill for a specific AI agent platform. |
31+
32+
## Command Options
33+
34+
<ResponseField name="--target, -t" type="string">
35+
36+
Install the [Checkly agent skill](/ai/skills) for a specific AI agent platform. Available platforms: `claude`, `cursor`, `windsurf`, `github-copilot`, `gemini-cli`, `codex`, `amp`.
37+
38+
**Usage:**
39+
40+
```bash Terminal
41+
npx checkly init --target=claude
42+
npx checkly init -t cursor
43+
```
44+
45+
</ResponseField>
46+
47+
## What to Expect
48+
49+
The `init` command detects your project context and adjusts its flow:
50+
51+
- **No `package.json`** — prompts you to create one before continuing.
52+
- **No Checkly config** — creates a `checkly.config.ts` and installs `checkly` and `jiti` as dev dependencies.
53+
- **Playwright detected** — provides context-aware setup that accounts for your existing test infrastructure.
54+
- **Existing Checkly project** — refreshes your agent skill to the latest version.
55+
56+
### AI-Assisted Setup
57+
58+
When you choose the AI-assisted path (or pass `--target`), the command:
59+
60+
1. Installs the [Checkly agent skill](/ai/skills) for your platform
61+
2. Creates a `checkly.config.ts` if one doesn't exist
62+
3. Installs dependencies
63+
4. Generates a starter prompt you can paste into your AI agent to begin configuring checks
64+
65+
<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>
66+
67+
### Manual Setup
68+
69+
When you choose the manual path, the command:
70+
71+
1. Creates a `checkly.config.ts` if one doesn't exist
72+
2. Installs dependencies
73+
3. Optionally copies example checks (API, browser, heartbeat, URL monitor) into a `__checks__` directory
74+
75+
### CI Mode
76+
77+
In CI environments (when `CI=true`), the command runs non-interactively and outputs setup instructions.
78+
79+
```bash Terminal
80+
CI=true npx checkly init
81+
```
82+
83+
## Examples
84+
85+
```bash Terminal
86+
# Interactive setup
87+
npx checkly init
88+
89+
# Set up with Claude Code agent skill
90+
npx checkly init --target=claude
91+
92+
# Non-interactive CI setup
93+
CI=true npx checkly init
94+
```
95+
96+
## Next Steps
97+
98+
After initialization, the typical workflow is:
99+
100+
1. **Log in** — `npx checkly login` to authenticate with your Checkly account
101+
2. **Test** — `npx checkly test --record` to dry-run your checks
102+
3. **Deploy** — `npx checkly deploy` to deploy checks to Checkly
103+
104+
## Related Commands
105+
106+
- [`checkly skills`](/cli/checkly-skills) - Print project context and install agent skills
107+
- [`checkly login`](/cli/checkly-login) - Log in to your Checkly account
108+
- [`checkly deploy`](/cli/checkly-deploy) - Deploy checks to Checkly

‎cli/checkly-pw-test.mdx‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,7 @@ Define `checkly pw-test` specific options before the `--` separator:
4242
| `--location, -l` | - | The location to run the checks at. |
4343
| `--private-location` | - | The private location to run checks at. |
4444
| `--[no-]record` | - | Record test results in Checkly as a test session with full logs, traces and videos. |
45+
| `--refresh-cache` | - | Force a fresh install of dependencies and update the cached version. |
4546
| `--reporter` | - | One or more custom reporters for the test output. Supports comma-separated values and repeated flags. |
4647
| `--stream-logs` | - | Stream logs from the test run to the console. |
4748
| `--test-session-name` | - | A name to use when storing results in Checkly |
@@ -187,6 +188,18 @@ npx checkly pw-test --private-location="staging-vpc"
187188

188189
</ResponseField>
189190

191+
<ResponseField name="--refresh-cache" type="boolean" default="false">
192+
193+
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.
194+
195+
**Usage:**
196+
197+
```bash Terminal
198+
npx checkly pw-test --refresh-cache
199+
```
200+
201+
</ResponseField>
202+
190203
<ResponseField name="--[no-]record" type="boolean">
191204

192205
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‎

Lines changed: 187 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,187 @@
1+
---
2+
title: checkly rca
3+
description: 'Trigger and retrieve AI-powered root cause analyses for error groups.'
4+
sidebarTitle: 'checkly rca'
5+
---
6+
7+
<Note>Available since CLI v7.8.0.</Note>
8+
9+
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.
10+
11+
<Accordion title="Prerequisites">
12+
Before using `checkly rca`, ensure you have:
13+
14+
- Checkly CLI installed
15+
- Valid Checkly account authentication (run `npx checkly login` if needed)
16+
- A Checkly plan that includes root cause analysis
17+
18+
For additional setup information, see [CLI overview](/cli/overview).
19+
</Accordion>
20+
21+
## Usage
22+
23+
```bash Terminal
24+
npx checkly rca <subcommand> [arguments] [options]
25+
```
26+
27+
## Subcommands
28+
29+
| Subcommand | Description |
30+
|------------|-------------|
31+
| `run` | Trigger a root cause analysis for an error group. |
32+
| `get` | Retrieve a root cause analysis by ID. |
33+
34+
## `checkly rca run`
35+
36+
Trigger a new root cause analysis for an error group. The analysis runs asynchronously — use `--watch` to wait for the result in your terminal.
37+
38+
**Usage:**
39+
40+
```bash Terminal
41+
npx checkly rca run [options]
42+
```
43+
44+
**Options:**
45+
46+
| Option | Required | Description |
47+
|--------|----------|-------------|
48+
| `--error-group, -e` | yes | The error group ID to analyze. |
49+
| `--watch, -w` | - | Wait for the analysis to complete and display the result. |
50+
| `--output, -o` | - | Output format: `detail`, `json`, or `md`. Default: `detail`. |
51+
52+
### Run Options
53+
54+
<ResponseField name="--error-group, -e" type="string">
55+
56+
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.
57+
58+
**Usage:**
59+
60+
```bash Terminal
61+
npx checkly rca run --error-group=<error-group-id>
62+
npx checkly rca run -e <error-group-id>
63+
```
64+
65+
</ResponseField>
66+
67+
<ResponseField name="--watch, -w" type="boolean" default="false">
68+
69+
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.
70+
71+
Only works with `--output detail`.
72+
73+
**Usage:**
74+
75+
```bash Terminal
76+
npx checkly rca run --error-group=<error-group-id> --watch
77+
npx checkly rca run -e <error-group-id> -w
78+
```
79+
80+
</ResponseField>
81+
82+
<ResponseField name="--output, -o" type="string" default="detail">
83+
84+
Set the output format. Use `json` for programmatic access or `md` for markdown.
85+
86+
**Usage:**
87+
88+
```bash Terminal
89+
npx checkly rca run --error-group=<error-group-id> --output=json
90+
npx checkly rca run -e <error-group-id> -o md
91+
```
92+
93+
</ResponseField>
94+
95+
### Run Examples
96+
97+
```bash Terminal
98+
# Trigger an RCA and wait for the result
99+
npx checkly rca run --error-group=err-abc-123 --watch
100+
101+
# Trigger an RCA without waiting
102+
npx checkly rca run --error-group=err-abc-123
103+
104+
# Get the result as JSON
105+
npx checkly rca run --error-group=err-abc-123 --output=json
106+
```
107+
108+
## `checkly rca get`
109+
110+
Retrieve an existing root cause analysis by its ID. If the analysis is still generating, use `--watch` to wait for completion.
111+
112+
**Usage:**
113+
114+
```bash Terminal
115+
npx checkly rca get <id> [options]
116+
```
117+
118+
**Arguments:**
119+
120+
| Argument | Description |
121+
|----------|-------------|
122+
| `id` | The RCA ID to retrieve. |
123+
124+
**Options:**
125+
126+
| Option | Required | Description |
127+
|--------|----------|-------------|
128+
| `--watch, -w` | - | Wait for the analysis to complete if still generating. |
129+
| `--output, -o` | - | Output format: `detail`, `json`, or `md`. Default: `detail`. |
130+
131+
### Get Options
132+
133+
<ResponseField name="--watch, -w" type="boolean" default="false">
134+
135+
Wait for the analysis to complete if it is still generating. Without this flag, the command returns the current status immediately.
136+
137+
Only works with `--output detail`.
138+
139+
**Usage:**
140+
141+
```bash Terminal
142+
npx checkly rca get <id> --watch
143+
npx checkly rca get <id> -w
144+
```
145+
146+
</ResponseField>
147+
148+
<ResponseField name="--output, -o" type="string" default="detail">
149+
150+
Set the output format. Use `json` for programmatic access or `md` for markdown.
151+
152+
**Usage:**
153+
154+
```bash Terminal
155+
npx checkly rca get <id> --output=json
156+
npx checkly rca get <id> -o md
157+
```
158+
159+
</ResponseField>
160+
161+
### Get Examples
162+
163+
```bash Terminal
164+
# Retrieve a completed RCA
165+
npx checkly rca get rca-xyz-789
166+
167+
# Wait for a pending RCA to complete
168+
npx checkly rca get rca-xyz-789 --watch
169+
170+
# Get the result as JSON
171+
npx checkly rca get rca-xyz-789 --output=json
172+
```
173+
174+
## RCA Output
175+
176+
A completed root cause analysis includes:
177+
178+
- **Classification** — the category of the error
179+
- **Root cause** — explanation of what caused the error
180+
- **User impact** — how the error affects end users
181+
- **Code fix** — suggested fix when available
182+
- **Evidence** — supporting artifacts from the analysis
183+
- **Reference links** — relevant external resources
184+
185+
## Related Commands
186+
187+
- [`checkly checks`](/cli/checkly-checks) - List, inspect, and analyze checks (includes error groups)

‎cli/checkly-test.mdx‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,7 @@ npx checkly test [arguments] [options]
2828
| `--location, -l` | - | The location to run the checks at. |
2929
| `--private-location` | - | The private location to run checks at. |
3030
| `--record` | - | Record test results in Checkly as a test session with full logs, traces and videos. |
31+
| `--refresh-cache` | - | Force a fresh install of dependencies and update the cached version. |
3132
| `--reporter, -r` | - | One or more custom reporters for the test output. Supports comma-separated values and repeated flags. |
3233
| `--retries` | - | How many times to retry a failing test run. |
3334
| `--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"
240241

241242
</ResponseField>
242243

244+
<ResponseField name="--refresh-cache" type="boolean" default="false">
245+
246+
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.
247+
248+
**Usage:**
249+
250+
```bash Terminal
251+
npx checkly test --refresh-cache
252+
```
253+
254+
</ResponseField>
255+
243256
<ResponseField name="--retries" type="number">
244257

245258
How many times to retry a failing test run. Default: 0, max: 3

‎cli/checkly-trigger.mdx‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,7 @@ npx checkly trigger [options]
2727
| `--location, -l` | - | The location to run the checks at. |
2828
| `--private-location` | - | The private location to run checks at. |
2929
| `--record` | - | Record check results in Checkly as a test session with full logs, traces and videos. |
30+
| `--refresh-cache` | - | Force a fresh install of dependencies and update the cached version. |
3031
| `--reporter, -r` | - | One or more custom reporters for the test output. Supports comma-separated values and repeated flags. |
3132
| `--retries` | - | How many times to retry a check run. |
3233
| `--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
284285
Records provide full visibility including logs, traces, and videos for debugging failed checks.
285286
</ResponseField>
286287

288+
<ResponseField name="--refresh-cache" type="boolean" default="false">
289+
290+
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.
291+
292+
**Usage:**
293+
294+
```bash Terminal
295+
npx checkly trigger --refresh-cache
296+
```
297+
298+
</ResponseField>
299+
287300
<ResponseField name="--retries" type="number" default="0">
288301

289302
How many times to retry a failed check run.

‎cli/installation.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ description: 'Creating a CLI project from scratch'
44
sidebarTitle: 'Installation'
55
---
66

7-
To kickstart a new project with the CLI, we recommend running `npm create checkly@latest`. But you can also add the CLI
7+
To kickstart a new project with the CLI, we recommend running `npx checkly init`. But you can also add the CLI
88
from scratch with the following steps.
99

1010
## Prerequisites

‎cli/overview.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ Get started by installing the CLI using the following command which will guide y
1616
set up a fully working example.
1717

1818
```bash Terminal
19-
npm create checkly@latest
19+
npx checkly init
2020
```
2121

2222
Now, login to your Checkly account or sign up for a new account right from the terminal.

0 commit comments

Comments
 (0)