checkly 0.0.0-canary.7166ed8

package/dist/ai-context/skills-command/references/investigate-checks.md

@@ -0,0 +1,156 @@
+# Inspecting Checks
+
+List and inspect deployed checks in your Checkly account.
+
+## List checks
+
+```bash
+npx checkly checks list
+npx checkly checks list --tag production --type PLAYWRIGHT
+npx checkly checks list --status failing
+npx checkly checks list --search "Homepage" --output json
+```
+
+Flags:
+- `-t, --tag <tag>` — filter by tag (repeat for multiple)
+- `--type <type>` — filter by check type (`API`, `BROWSER`, `HEARTBEAT`, `MULTI_STEP`, `PLAYWRIGHT`, `TCP`, `ICMP`, `DNS`, `URL`, `AGENTIC`)
+- `-s, --search <name>` — filter by name (case-insensitive partial match)
+- `--status <status>` — filter by current status: `passing`, `failing`, or `degraded`
+- `-l, --limit <n>` — max checks to return (1-100, default 25)
+- `-p, --page <n>` — page number
+- `-o, --output <format>` — `table` (default), `json`, or `md`
+
+## Get check details
+
+```bash
+npx checkly checks get <check-id>
+npx checkly checks get <check-id> --output json
+npx checkly checks get <check-id> --stats-range last7Days --group-by location
+```
+
+Shows check configuration, recent results, error groups, and analytics stats.
+
+Flags:
+- `-r, --result <result-id>` — drill into a specific result (see below)
+- `--include-attempts` — with `--result`, also list the individual retry attempts for that result (see below)
+- `-e, --error-group <error-group-id>` — show full details for a specific error group
+- `--results-limit <n>` — number of recent results to show (default 10)
+- `--results-cursor <cursor>` — paginate results using the cursor from previous output
+- `--stats-range <range>` — analytics range: `last24Hours` (default), `last7Days`, `last30Days`, `thisWeek`, `thisMonth`, `lastWeek`, `lastMonth`
+- `--group-by <dimension>` — group stats by `location` or `statusCode`
+- `--metrics <list>` — comma-separated list of metrics to show (overrides defaults)
+- `--filter-status <status>` — only include runs with this status in stats: `success` or `failure`
+- `-o, --output <format>` — `detail` (default), `json`, or `md`
+
+**Important:** Look for `errorGroups`, `rootCause` or `RCA` to investigate a root cause. If available, let the user know that Rocky AI (Checkly's AI agent) evaluated the issue already and reuse all available information.
+
+### View a specific check result
+
+```bash
+npx checkly checks get <check-id> --result <result-id>
+npx checkly checks get <check-id> --result <result-id> --output json
+```
+
+### View retry attempts for a result
+
+When a check has retries enabled, a single run produces one `FINAL` result plus
+one `ATTEMPT` result for each earlier failed try (all sharing a `sequenceId`).
+By default only the `FINAL` result is shown. Add `--include-attempts` to list the
+full retry sequence — attempt number, status, location, duration, and a short
+error summary:
+
+```bash
+npx checkly checks get <check-id> --result <result-id> --include-attempts
+npx checkly checks get <check-id> --result <result-id> --include-attempts --output json
+```
+
+With `--include-attempts --output json`, the command returns a stable envelope:
+
+```json
+{
+  "result": {},
+  "attempts": []
+}
+```
+
+Use the `attempts` array to inspect intermediate retry failures. Use the `result`
+object for the requested result row.
+
+### List or download result assets
+
+Result detail output summarizes available screenshots, traces, and videos when
+present. Use the dedicated asset manifest commands to inspect exact asset names
+and download files:
+
+```bash
+npx checkly assets list --check-id <check-id> --result-id <result-id>
+npx checkly assets list --check-id <check-id> --result-id <result-id> --type trace --view tree
+npx checkly assets list --check-id <check-id> --result-id <result-id> --output json
+npx checkly assets download --check-id <check-id> --result-id <result-id> --asset "<Asset>"
+npx checkly assets download --check-id <check-id> --result-id <result-id> --type all --dir ./checkly-assets
+```
+
+Run `assets list` first to discover available files. The default table output
+has an `Asset` column; copy that value into `--asset` for single-file downloads.
+
+Flags:
+- `--type <type>` - filter/select by `log`, `trace`, `video`, `screenshot`, `pcap`, `report`, `file`, or `all`.
+- `--asset <value>` - exact Asset/Name value or glob. Prefer copying the `Asset` value from the default table output before downloading a single file.
+- `--dir <path>` - destination directory for downloads; defaults under `./checkly-assets/`.
+- `--force` / `--skip-existing` - overwrite or preserve existing files.
+
+`assets list --output json` uses a stable list envelope:
+
+```json
+{
+  "data": [],
+  "pagination": {
+    "length": 0
+  }
+}
+```
+
+`assets download` requires `--type` or `--asset` unless the manifest is a single
+archive bundle. Archive entries download as their containing archive; filters
+narrow the manifest list, not the archive bytes.
+
+Do not invent asset names or assume every result has the same artifact set. Some
+results have screenshots only, some have traces or videos, and some have no
+downloadable assets.
+
+### View an error group
+
+```bash
+npx checkly checks get <check-id> --error-group <error-group-id>
+```
+
+## Check analytics and stats
+
+```bash
+npx checkly checks stats
+npx checkly checks stats --range last7Days --tag production
+npx checkly checks stats <check-id-1> <check-id-2>
+npx checkly checks stats --output json
+```
+
+Shows availability, response times, error counts, and other metrics for your checks.
+
+Flags:
+- `-r, --range <range>` — time range: `last24Hours` (default), `last7Days`, `thisWeek`, `lastWeek`, `lastMonth`
+- `-t, --tag <tag>` — filter by tag (repeat for multiple)
+- `--type <type>` — filter by check type
+- `-s, --search <name>` — filter by name
+- `-l, --limit <n>` — max checks to return (1-100, default 25)
+- `-p, --page <n>` — page number
+- `-o, --output <format>` — `table` (default), `json`, or `md`
+
+Pass one or more check IDs as positional arguments to get stats for specific checks only.
+
+## Trigger checks
+
+```bash
+npx checkly trigger --tags production
+npx checkly trigger --tags critical,api
+```
+
+Triggers existing deployed checks by tag. Useful for on-demand verification.

package/dist/ai-context/skills-command/references/investigate-test-sessions.md

@@ -0,0 +1,165 @@
+# Investigating Test Sessions
+
+Use this flow when a user asks you to run a session, inspect recorded test-session results, investigate test-session error groups, run root cause analysis, or retrieve result logs, traces, videos, screenshots, and other assets.
+
+Read-only inspection commands execute immediately. `rca run` starts a new analysis, but it does not mutate checks or monitors.
+
+## Run or trigger a recorded session
+
+`checkly test`, `checkly trigger`, and `checkly pw-test` record results as a test session by default. Use `--no-record` only when the user explicitly does not want a recorded session.
+
+```bash
+npx checkly test --detach --test-session-name "Checkout regression"
+npx checkly test --record --detach --test-session-name "Checkout regression"
+npx checkly trigger --detach --tags production --test-session-name "Production smoke"
+npx checkly pw-test --detach --test-session-name "Playwright suite"
+```
+
+For agent workflows, prefer `--detach` when starting recorded sessions. The command schedules the session, prints the `Test session ID`, and exits without waiting for completion. Inspect the session with `npx checkly test-sessions get <test-session-id> --watch` instead of relying on Checkly UI links.
+
+Useful flags:
+- `--location <region>` or `--private-location <slug>` - choose where checks run.
+- `-e, --env KEY=value` or `--env-file <path>` - pass runtime environment variables.
+- `--timeout <seconds>` - wait for session completion before the command exits; ignored when `--detach` exits after scheduling.
+- `-d, --detach` - start the session in the cloud, print the test session ID, and exit immediately; preferred for agents starting recorded sessions.
+
+Do not combine `--detach` with file reporters such as `--reporter json` or `--reporter github`. Detached runs exit before results are available, so no result report can be written. After scheduling with `--detach`, use `test-sessions get --output json` for machine-readable session details.
+
+If the command output includes a test session ID or link, use the ID directly with `test-sessions get`.
+
+## Find a test session
+
+```bash
+npx checkly test-sessions list
+npx checkly test-sessions list --status failed --limit 10
+npx checkly test-sessions list --branch main --provider github
+npx checkly test-sessions list --search "checkout"
+npx checkly test-sessions list --error-group <test-session-error-group-id>
+npx checkly test-sessions list --output json
+```
+
+Flags:
+- `-l, --limit <n>` - number of sessions to return (1-100, default 20).
+- `--cursor <nextId>` - fetch the next cursor page.
+- `--from <date>` / `--to <date>` - filter by ISO date or Unix timestamp in seconds.
+- `--status <status>` - `running`, `failed`, `passed`, or `cancelled`; repeat or comma-separate.
+- `--provider <provider>` - `github`, `vercel`, `api`, `trigger`, or `pw_reporter`; repeat or comma-separate.
+- `--branch <name>` - filter by Git branch; repeat or comma-separate.
+- `--user <id>` and `--no-users` - filter by commit owner/invoking user, or include sessions without either.
+- `-s, --search <text>` - search test-session text fields.
+- `--error-group <id>` - find sessions that include a specific test-session error group.
+- `-o, --output <format>` - `table` (default), `json`, or `md`.
+
+JSON output uses the stable list envelope:
+
+```json
+{
+  "data": [],
+  "pagination": {
+    "nextId": null,
+    "length": 0
+  }
+}
+```
+
+## Inspect a test session
+
+```bash
+npx checkly test-sessions get <test-session-id>
+npx checkly test-sessions get <test-session-id> --watch
+npx checkly test-sessions get <test-session-id> --output json
+npx checkly test-sessions get <test-session-id> --error-groups-limit 20
+```
+
+Flags:
+- `-w, --watch` - wait for a running session to complete before rendering.
+- `--error-groups-limit <n>` - number of error group IDs to show in detail output (default 5).
+- `-o, --output <format>` - `detail` (default), `json`, or `md`.
+
+The detail view shows the session status, metadata, result rows, test-session result IDs, check IDs when available, and test-session error group IDs. Prefer `--watch` before investigating failures so you do not act on partial results.
+
+Use `--output json` when you need exact fields, result links, check IDs, or test-session result IDs. For downloadable logs, traces, videos, screenshots, reports, and files, use `checkly assets list` and `checkly assets download` with the test session ID and result ID.
+
+## Inspect a test-session error group
+
+Use only error group IDs shown by `test-sessions get`. Test-session error groups are separate from check error groups, so do not pass them to `checks get --error-group`.
+
+```bash
+npx checkly test-sessions get <test-session-id> --error-group <test-session-error-group-id>
+npx checkly test-sessions get <test-session-id> --error-group <test-session-error-group-id> --full-error
+npx checkly test-sessions get <test-session-id> --error-group <test-session-error-group-id> --output json
+```
+
+Flags:
+- `--full-error` - print the complete raw error for the selected test-session error group.
+- `-w, --watch` - wait for session completion before validating and fetching the error group.
+- `-o, --output <format>` - `detail` (default), `json`, or `md`.
+
+Look for `rootCauseAnalyses` in JSON output. If one already exists, reuse it before starting a new RCA.
+
+## Run root cause analysis
+
+For test-session error groups, use `--test-session-error-group` (short alias `-te`). For regular check error groups, use `--error-group` (short alias `-e`).
+
+```bash
+npx checkly rca run --test-session-error-group <test-session-error-group-id> --watch
+npx checkly rca run -te <test-session-error-group-id> --user-context "Started after checkout deploy" --watch
+npx checkly rca get <rca-id> --watch
+```
+
+Flags:
+- `--user-context <text>` - add concise context that can improve the analysis.
+- `-w, --watch` - wait for completion and print the analysis.
+- `-o, --output <format>` - `detail` (default), `json`, or `md`; watch mode is only supported with detail output.
+
+If RCA is unavailable because of plan or entitlement limits, run `npx checkly account plan --output json` and report the relevant entitlement or upgrade URL.
+
+## Retrieve result assets
+
+Use the asset manifest commands for recorded test-session result files. Start
+from `test-sessions get` to identify the `testSessionResultId` (and `checkId`
+when available) for the row you want to inspect.
+
+```bash
+npx checkly test-sessions get <test-session-id> --output json
+npx checkly assets list --test-session-id <test-session-id> --result-id <test-session-result-id>
+npx checkly assets list --test-session-id <test-session-id> --result-id <test-session-result-id> --type trace --view tree
+npx checkly assets list --test-session-id <test-session-id> --result-id <test-session-result-id> --output json
+npx checkly assets download --test-session-id <test-session-id> --result-id <test-session-result-id> --asset "<Asset>"
+npx checkly assets download --test-session-id <test-session-id> --result-id <test-session-result-id> --type all --dir ./checkly-assets
+```
+
+Run `assets list` first to discover available files. The default table output
+has an `Asset` column; copy that value into `--asset` for single-file downloads.
+
+Flags:
+- `--type <type>` - filter/select by `log`, `trace`, `video`, `screenshot`, `pcap`, `report`, `file`, or `all`.
+- `--asset <value>` - exact Asset/Name value or glob. Prefer copying the `Asset` value from `assets list --view table` for single-file downloads.
+- `--dir <path>` - destination directory for downloads; defaults under `./checkly-assets/`.
+- `--force` / `--skip-existing` - overwrite or preserve existing files.
+
+`assets list --output json` uses a stable list envelope:
+
+```json
+{
+  "data": [],
+  "pagination": {
+    "length": 0
+  }
+}
+```
+
+`assets download` requires `--type` or `--asset` unless the manifest is a single
+archive bundle. Archive entries download as their containing archive; filters
+narrow the manifest list, not the archive bytes.
+
+If you also need the scheduled check result view for the same row, and the row
+has a `checkId`, use:
+
+```bash
+npx checkly checks get <check-id> --result <test-session-result-id>
+```
+
+Do not invent asset names or assume every result has the same artifact set. Some
+results have screenshots only, some have traces or videos, and some have no
+downloadable assets.

package/dist/ai-context/skills-command/references/investigate.md

@@ -0,0 +1,15 @@
+# Investigating Check Status and Errors
+
+Access check status, analyze failures, and investigate errors across your Checkly account.
+
+Read-only commands execute immediately without confirmation.
+
+## Available Commands
+
+Parse and read further reference documentation when tasked with investigating any of the following:
+
+### `npx checkly skills investigate checks`
+Inspect checks (`checks list`, `checks get`), retry attempts, result assets, and trigger on-demand runs
+
+### `npx checkly skills investigate test-sessions`
+Run and inspect recorded test sessions, drill into test-session error groups, run RCA, and list/download result assets

package/dist/ai-context/skills-command/references/manage-account-members.md

@@ -0,0 +1,82 @@
+# Account Members
+
+List active account members and pending or expired account invites. Update active member roles and delete active members.
+
+## Usage
+
+```bash
+npx checkly members
+npx checkly members --output json
+npx checkly members --search alice
+npx checkly members --type invite --status pending
+npx checkly members --role admin
+npx checkly members --limit 25
+npx checkly members --hide-id
+npx checkly members update alice@example.com --role read_run
+npx checkly members update <user-id> --role admin --id --force
+npx checkly members delete alice@example.com --force
+```
+
+Flags:
+- `--search <term>` — match member names, member emails, and invite emails.
+- `--type <type>` — `member` or `invite` (case-insensitive).
+- `--role <role>` — `owner`, `admin`, `read_write`, `read_run`, or `read_only` (case-insensitive).
+- `--status <status>` — `active`, `pending`, or `expired` (case-insensitive).
+- `-l, --limit <n>` — number of rows to return, from 1 to 100.
+- `--next-id <cursor>` — cursor for the next page. Requires `--limit`.
+- `-o, --output <format>` — `table` (default), `json`, or `md`.
+- `--hide-id` — hide member and invite IDs in table output.
+
+Role update:
+- `checkly members update <member> --role <role>` updates an active account member role.
+- `<member>` can be an email address or user ID. Values containing `@` are resolved as exact member emails by default; other values are treated as user IDs.
+- Use `--email` or `--id` to force how `<member>` is interpreted.
+- Valid update roles are `admin`, `read_write`, `read_run`, and `read_only` (case-insensitive).
+- `owner` cannot be set through this command.
+- This mutation requires confirmation. In non-interactive mode, rerun with `--force` after reviewing the confirmation preview.
+
+Delete member:
+- `checkly members delete <member>` removes an active account member.
+- `<member>` can be an email address or user ID. Values containing `@` are resolved as exact member emails by default; other values are treated as user IDs.
+- Use `--email` or `--id` to force how `<member>` is interpreted.
+- This destructive mutation requires confirmation. In non-interactive mode, rerun with `--force` after reviewing the confirmation preview.
+- Pending invite cancellation is not handled by this command.
+
+## JSON response shape
+
+```json
+{
+  "members": [
+    {
+      "type": "member",
+      "accountId": "11111111-1111-1111-1111-111111111111",
+      "userId": "22222222-2222-2222-2222-222222222222",
+      "name": "Owner User",
+      "email": "owner@example.com",
+      "role": "OWNER",
+      "status": "ACTIVE",
+      "createdAt": "2026-01-01T00:00:00.000Z",
+      "updatedAt": "2026-01-02T00:00:00.000Z",
+      "isSupportMembership": false,
+      "ssoEnabled": false,
+      "mfaEnabled": true
+    },
+    {
+      "type": "invite",
+      "id": "33333333-3333-3333-3333-333333333333",
+      "accountId": "11111111-1111-1111-1111-111111111111",
+      "email": "pending@example.com",
+      "role": "READ_ONLY",
+      "status": "PENDING",
+      "inviterEmail": "owner@example.com",
+      "createdAt": "2026-01-03T00:00:00.000Z",
+      "updatedAt": "2026-01-03T00:00:00.000Z",
+      "expiresAt": "2026-02-03T00:00:00.000Z"
+    }
+  ],
+  "length": 2,
+  "nextId": null
+}
+```
+
+Member roles are returned as `OWNER`, `ADMIN`, `READ_WRITE`, `READ_RUN`, or `READ_ONLY`. Invite roles exclude `OWNER`. Invite statuses are returned as `PENDING` or `EXPIRED`.

package/dist/ai-context/skills-command/references/manage-plan.md

@@ -0,0 +1,49 @@
+# Account Plan and Entitlements
+
+Show your account plan, entitlements, feature limits, and available locations.
+
+## Usage
+
+```bash
+npx checkly account plan                          # Summary view (metered limits + flag count)
+npx checkly account plan --output json             # Full JSON (recommended for agents)
+npx checkly account plan --disabled                # Show only features not on your plan
+npx checkly account plan --disabled --type flag    # Disabled flags only
+npx checkly account plan --type metered            # Metered limits only
+npx checkly account plan --search "browser"        # Search by name or description
+npx checkly account plan BROWSER_CHECKS            # Detail view for one entitlement
+npx checkly account plan --help                    # Full flag reference
+```
+
+## JSON response shape (abbreviated)
+
+```json
+{
+  "plan": "hobby",
+  "planDisplayName": "Hobby",
+  "checkoutUrl": "https://app.checklyhq.com/accounts/.../billing/checkout",
+  "contactSalesUrl": "https://www.checklyhq.com/contact-sales/",
+  "locations": {
+    "all": [
+      { "id": "us-east-1", "name": "N. Virginia", "available": true },
+      { "id": "eu-west-1", "name": "Ireland", "available": false }
+    ],
+    "maxPerCheck": 3
+  },
+  "entitlements": [
+    { "key": "BROWSER_CHECKS", "type": "metered", "enabled": true, "quantity": 10 },
+    {
+      "key": "PRIVATE_LOCATIONS", "type": "metered", "enabled": false,
+      "requiredPlan": "TEAM", "requiredPlanDisplayName": "Team",
+      "upgradeUrl": "https://app.checklyhq.com/accounts/.../billing/checkout"
+    }
+  ]
+}
+```
+
+## How to use this data
+
+1. **Locations:** Filter `locations.all` to entries where `available === true`. Use only those IDs in `checkly.config.ts` and check constructs. Respect `maxPerCheck` as the upper bound per check.
+2. **Metered entitlements:** Check `quantity` for limits. `enabled: false` means the feature is not available.
+3. **Flag entitlements:** `enabled: true` means available, `false` means not on this plan.
+4. **Disabled features:** Each includes an `upgradeUrl`. Share this with the user — it points to the self-service checkout page or the enterprise contact sales page depending on the required plan.

package/dist/ai-context/skills-command/references/manage.md

@@ -0,0 +1,53 @@
+# Account Management
+
+Understand your account's plan, entitlements, limits, members, and pending invites.
+
+## Plan-aware workflow
+
+Checkly accounts have different capabilities depending on the plan (Hobby, Starter, Team, Enterprise) and add-ons (Communicate, Resolve). Features like locations, retry strategies, frequencies, and alert channels vary by plan.
+
+**Before writing or modifying checks, run:**
+
+```bash
+npx checkly account plan --output json
+```
+
+This returns your entitlements (enabled/disabled with limits), available locations, and upgrade URLs. Use this to:
+
+- **Filter locations** to only those where `available` is `true` in `locations.all`
+- **Check feature flags** before using constructs (e.g. private locations, advanced alert channels)
+- **Respect metered limits** (e.g. max browser checks, max alert channels)
+- **Surface upgrade paths** when a feature is disabled — each disabled entitlement includes an `upgradeUrl` pointing to the self-service checkout or the contact sales page
+
+## Applying entitlements to check configuration
+
+Entitlement keys follow the pattern `{CHECK_TYPE}_{FEATURE}` — match them to the check type you're configuring. Before setting any property on a check construct, find the corresponding entitlement and verify it's enabled.
+
+**Common plan-gated properties that agents get wrong on first setup:**
+
+| Check property | Entitlement pattern to search | What to do if disabled |
+|---|---|---|
+| `retryStrategy` | `*_RETRY_STRATEGY_*` and `*_MAX_RETRIES_*` for your check type | Omit `retryStrategy` entirely, or use `RetryStrategyBuilder.noRetries()` |
+| `runParallel` | `*_SCHEDULING_STRATEGY_PARALLEL` for your check type | Omit `runParallel` or set to `false` (use round-robin) |
+| `frequency` | `*_FREQ_*` for your check type | Use only frequencies where the entitlement is enabled |
+| `locations` | `locations.all` array | Use only locations where `available` is `true` |
+| `privateLocation` | `PRIVATE_LOCATIONS` | Only available on Team plan and above |
+
+**How to check:** Use `--search` to narrow entitlements for the check type you're configuring:
+
+```bash
+npx checkly account plan --output json --search "uptime"
+npx checkly account plan --disabled --search "retry"
+```
+
+**When a feature is disabled:** Do not use it. Omit the property from the construct — Checkly will apply safe defaults. If the user needs the feature, share the `upgradeUrl` from the entitlement.
+
+## Available Commands
+
+Parse and read further reference documentation for any of the following:
+
+### `npx checkly skills manage plan`
+Check account plan, entitlements, feature limits, and available locations (`account plan`)
+
+### `npx checkly skills manage account-members`
+List account members and pending invites (`members`), update member roles, and delete members

package/dist/auth/index.d.ts

@@ -0,0 +1,15 @@
+export type AuthMode = 'signup' | 'login';
+export declare function generatePKCE(): {
+    codeChallenge: string;
+    codeVerifier: string;
+};
+export declare class AuthContext {
+    #private;
+    private mode;
+    authenticationUrl: string;
+    constructor(mode: AuthMode);
+    getAuth0Credentials(): Promise<{
+        name: any;
+        key: any;
+    }>;
+}