Merge branch 'main' into giordanodaniel-ai-messaging-update

Author: Dgiordano33

.github/workflows/update-api-spec.yml

@@ -10,51 +10,51 @@ jobs:
   update-api-spec:
     runs-on: ubuntu-latest
     timeout-minutes: 10
-    
+
     permissions:
       contents: write
       pull-requests: write
-    
+
     steps:
     - name: Checkout repository
       uses: actions/checkout@v4
       with:
         token: ${{ secrets.GITHUB_TOKEN }}
-    
+
     - name: Set up Node.js
       uses: actions/setup-node@v4
       with:
         node-version: '20'
-    
+
     - name: Install dependencies
       run: |
         npm install -g swagger2openapi
         npm install -g mintlify
-    
+
     - name: Configure git
       run: |
         git config user.name "API Spec Updater"
         git config user.email "noreply@checkly.com"
-    
+
     - name: Fetch and update API specification
       run: |
         # Store current spec hash for comparison
         CURRENT_HASH=$(sha256sum api-reference/openapi.json | cut -d' ' -f1)
-        
+
         # Run the update script
         ./update-api-spec.sh
-        
+
         # Check if spec actually changed
         NEW_HASH=$(sha256sum api-reference/openapi.json | cut -d' ' -f1)
-        
+
         if [ "$CURRENT_HASH" != "$NEW_HASH" ]; then
           echo "API specification has changed"
           echo "spec_changed=true" >> $GITHUB_ENV
         else
           echo "API specification is unchanged"
           echo "spec_changed=false" >> $GITHUB_ENV
         fi
-    
+
     - name: Commit and Push Changes
       if: env.spec_changed == 'true'
       run: |
@@ -66,8 +66,12 @@ jobs:
 
         # Push directly to main
         git push origin main
-    
+
     - name: Report no changes
       if: env.spec_changed == 'false'
       run: |
-        echo "✅ API specification is up to date - no changes needed"
+        echo "✅ API specification is up to date - no changes needed"
+
+    - name: Ping Checkly
+      run: curl -fsS --retry 3 https://ping.checklyhq.com/ad576f21-3f3e-4a6a-b8e4-67fd0f6ed92d
+

api-reference/openapi.json

@@ -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-init.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.