Merge branch 'main' into michelle/red-71-soft-diagnostics-for-logicalid-validation

Author: miliberlin

packages/cli/e2e/__tests__/account-plan.spec.ts

@@ -0,0 +1,186 @@
+import config from 'config'
+import { describe, it, expect } from 'vitest'
+
+import { runChecklyCli } from '../run-checkly'
+
+describe('checkly account plan', () => {
+  it('should show plan summary with default output', async () => {
+    const result = await runChecklyCli({
+      args: ['account', 'plan'],
+      apiKey: config.get('apiKey'),
+      accountId: config.get('accountId'),
+    })
+    expect(result.status).toBe(0)
+    expect(result.stdout).toContain('Plan:')
+    expect(result.stdout).toContain('Metered entitlements')
+    expect(result.stdout).toContain('additional features enabled')
+  })
+
+  it('should output valid JSON with --output json', async () => {
+    const result = await runChecklyCli({
+      args: ['account', 'plan', '--output', 'json'],
+      apiKey: config.get('apiKey'),
+      accountId: config.get('accountId'),
+    })
+    expect(result.status).toBe(0)
+    const parsed = JSON.parse(result.stdout)
+    expect(parsed).toHaveProperty('plan')
+    expect(parsed).toHaveProperty('planDisplayName')
+    expect(parsed).toHaveProperty('addons')
+    expect(parsed).toHaveProperty('entitlements')
+    expect(Array.isArray(parsed.entitlements)).toBe(true)
+    expect(parsed.entitlements.length).toBeGreaterThan(0)
+    expect(parsed.entitlements[0]).toHaveProperty('key')
+    expect(parsed.entitlements[0]).toHaveProperty('type')
+    expect(parsed.entitlements[0]).toHaveProperty('enabled')
+  })
+
+  it('should output markdown with --output md', async () => {
+    const result = await runChecklyCli({
+      args: ['account', 'plan', '--output', 'md'],
+      apiKey: config.get('apiKey'),
+      accountId: config.get('accountId'),
+    })
+    expect(result.status).toBe(0)
+    expect(result.stdout).toContain('# Plan:')
+    expect(result.stdout).toContain('| Name | Limit |')
+  })
+
+  it('should show detail view for a specific entitlement key', async () => {
+    const result = await runChecklyCli({
+      args: ['account', 'plan', 'BROWSER_CHECKS'],
+      apiKey: config.get('apiKey'),
+      accountId: config.get('accountId'),
+    })
+    expect(result.status).toBe(0)
+    expect(result.stdout).toContain('BROWSER_CHECKS')
+    expect(result.stdout).toContain('Browser checks')
+  })
+
+  it('should output single entitlement as JSON', async () => {
+    const result = await runChecklyCli({
+      args: ['account', 'plan', 'BROWSER_CHECKS', '--output', 'json'],
+      apiKey: config.get('apiKey'),
+      accountId: config.get('accountId'),
+    })
+    expect(result.status).toBe(0)
+    const parsed = JSON.parse(result.stdout)
+    expect(parsed.key).toBe('BROWSER_CHECKS')
+    expect(parsed.type).toBe('metered')
+  })
+
+  it('should filter by --type metered', async () => {
+    const result = await runChecklyCli({
+      args: ['account', 'plan', '--type', 'metered'],
+      apiKey: config.get('apiKey'),
+      accountId: config.get('accountId'),
+    })
+    expect(result.status).toBe(0)
+    expect(result.stdout).toContain('LIMIT')
+    expect(result.stdout).toContain('entitlement')
+  })
+
+  it('should filter by --type flag', async () => {
+    const result = await runChecklyCli({
+      args: ['account', 'plan', '--type', 'flag'],
+      apiKey: config.get('apiKey'),
+      accountId: config.get('accountId'),
+    })
+    expect(result.status).toBe(0)
+    expect(result.stdout).toContain('ENABLED')
+    expect(result.stdout).toContain('entitlement')
+  })
+
+  it('should filter by --search', async () => {
+    const result = await runChecklyCli({
+      args: ['account', 'plan', '--search', 'browser'],
+      apiKey: config.get('apiKey'),
+      accountId: config.get('accountId'),
+    })
+    expect(result.status).toBe(0)
+    expect(result.stdout).toContain('Browser')
+    expect(result.stdout).toContain('entitlement')
+  })
+
+  it('should fail for unknown entitlement key', async () => {
+    const result = await runChecklyCli({
+      args: ['account', 'plan', 'NONEXISTENT_KEY'],
+      apiKey: config.get('apiKey'),
+      accountId: config.get('accountId'),
+    })
+    expect(result.status).toBe(2)
+    expect(result.stderr).toContain('not found')
+  })
+
+  it('should fail when combining key with --type', async () => {
+    const result = await runChecklyCli({
+      args: ['account', 'plan', 'BROWSER_CHECKS', '--type', 'metered'],
+      apiKey: config.get('apiKey'),
+      accountId: config.get('accountId'),
+    })
+    expect(result.status).not.toBe(0)
+  })
+
+  it('should show REQUIRED UPGRADE column in summary view', async () => {
+    const result = await runChecklyCli({
+      args: ['account', 'plan'],
+      apiKey: config.get('apiKey'),
+      accountId: config.get('accountId'),
+    })
+    expect(result.status).toBe(0)
+    expect(result.stdout).toContain('REQUIRED UPGRADE')
+  })
+
+  it('should show billing checkout link', async () => {
+    const result = await runChecklyCli({
+      args: ['account', 'plan'],
+      apiKey: config.get('apiKey'),
+      accountId: config.get('accountId'),
+    })
+    expect(result.status).toBe(0)
+    expect(result.stdout).toContain('billing/checkout')
+  })
+
+  it('should include checkoutUrl and contactSalesUrl in JSON output', async () => {
+    const result = await runChecklyCli({
+      args: ['account', 'plan', '--output', 'json'],
+      apiKey: config.get('apiKey'),
+      accountId: config.get('accountId'),
+    })
+    expect(result.status).toBe(0)
+    const parsed = JSON.parse(result.stdout)
+    expect(parsed).toHaveProperty('checkoutUrl')
+    expect(parsed.checkoutUrl).toContain('billing/checkout')
+    expect(parsed).toHaveProperty('contactSalesUrl')
+    expect(parsed.contactSalesUrl).toContain('contact-sales')
+  })
+
+  it('should filter with --disabled flag', async () => {
+    const result = await runChecklyCli({
+      args: ['account', 'plan', '--disabled'],
+      apiKey: config.get('apiKey'),
+      accountId: config.get('accountId'),
+    })
+    expect(result.status).toBe(0)
+    expect(result.stdout).toContain('entitlement')
+  })
+
+  it('should combine --disabled with --type', async () => {
+    const result = await runChecklyCli({
+      args: ['account', 'plan', '--disabled', '--type', 'flag'],
+      apiKey: config.get('apiKey'),
+      accountId: config.get('accountId'),
+    })
+    expect(result.status).toBe(0)
+    expect(result.stdout).toContain('REQUIRED UPGRADE')
+  })
+
+  it('should fail when combining key with --disabled', async () => {
+    const result = await runChecklyCli({
+      args: ['account', 'plan', 'BROWSER_CHECKS', '--disabled'],
+      apiKey: config.get('apiKey'),
+      accountId: config.get('accountId'),
+    })
+    expect(result.status).not.toBe(0)
+  })
+})

packages/cli/e2e/__tests__/help.spec.ts

@@ -49,6 +49,7 @@ describe('help', () => {
   trigger  Trigger your existing checks on Checkly.`)
 
     expect(stdout).toContain(`ADDITIONAL COMMANDS
+  account          View and manage your Checkly account.
   checks           List and inspect checks in your Checkly account.
   destroy          Destroy your project with all its related resources.
   env              Manage Checkly environment variables.

packages/cli/e2e/__tests__/whoami.spec.ts

@@ -11,5 +11,6 @@ describe('whomai', () => {
       accountId: config.get('accountId'),
     })
     expect(stdout).toContain(config.get('accountName'))
+    expect(stdout).toContain('Plan:')
   })
 })

packages/cli/package.json

@@ -64,6 +64,9 @@
       "message": "<%= config.name %> update available from <%= chalk.greenBright(config.version) %> to <%= chalk.greenBright(latest) %>. To update, run `npm install -D checkly@latest`"
     },
     "topics": {
+      "account": {
+        "description": "View and manage your Checkly account."
+      },
       "checks": {
         "description": "List and inspect checks in your Checkly account."
       },
@@ -76,9 +79,6 @@
       "import": {
         "description": "Import existing resources from your Checkly account to your project."
       },
-      "skills": {
-        "description": "Explore Checkly AI agent skills, actions and reference documentation."
-      },
       "status-pages": {
         "description": "List and manage status pages in your Checkly account."
       }

packages/cli/src/ai-context/README.md

@@ -26,6 +26,10 @@ Agent Skills are a standardized format for giving AI agents specialized knowledg
 - Build dashboards and status pages
 - Follow monitoring-as-code best practices with the Checkly CLI
 
+## Installing This Skill
+
+Run `npx checkly skills install` to install the skill into your project. The command supports Claude Code, Cursor, Codex and more out of the box, or you can specify a custom path.
+
 ## Using This Skill
 
 AI agents can load this skill to gain expertise in Checkly monitoring. The skill follows the [Agent Skills specification](https://agentskills.io) with:

packages/cli/src/ai-context/context.ts

@@ -63,6 +63,13 @@ export const COMMUNICATE_REFERENCES = [
   },
 ] as const
 
+export const MANAGE_REFERENCES = [
+  {
+    id: 'manage-plan',
+    description: 'Check account plan, entitlements, feature limits, and available locations (`account plan`)',
+  },
+] as const
+
 export const SKILL = {
   name: 'checkly',
   description: 'Get all the information and context to let your agent initialize, set up, create, test and manage your monitoring checks using the Checkly CLI.',
@@ -88,6 +95,11 @@ export const ACTIONS = [
     description: 'Open incidents and lead customer communications via status pages.',
     references: COMMUNICATE_REFERENCES,
   },
+  {
+    id: 'manage',
+    description: 'Understand your account plan, entitlements, and feature limits.',
+    references: MANAGE_REFERENCES,
+  },
 ] as const
 
 interface ExampleConfig {

packages/cli/src/ai-context/references/communicate-incidents.md

@@ -67,9 +67,13 @@ Flags:
 
 ## Status pages
 
-Use `npx checkly status-pages list` to find status page IDs and their services. Use `--output json` to get machine-readable service IDs for incident creation.
+Use `npx checkly status-pages list` to find status page IDs, and `npx checkly status-pages get` for full details including cards and services.
 
 ```bash
 npx checkly status-pages list
 npx checkly status-pages list --output json
+npx checkly status-pages get <status-page-id>
+npx checkly status-pages get <status-page-id> --output json
 ```
+
+Use `--output json` to get machine-readable service IDs for incident creation.

packages/cli/src/ai-context/references/configure.md

@@ -46,6 +46,18 @@ If the Checkly CLI is installed (`npx checkly version`), use `npx checkly skills
 
 <!-- REFERENCE_COMMANDS -->
 
+## Check Locations and Plan Entitlements
+
+Not all features and locations are available on all plans. **Before configuring checks, run:**
+
+```bash
+npx checkly account plan --output json
+```
+
+This returns your exact entitlements and available locations. Use only locations where `available` is `true` in the `locations.all` array. If a feature is disabled, the response includes an `upgradeUrl` to share with the user.
+
+Run `npx checkly skills manage plan` for the full reference.
+
 ## Testing and Debugging
 
 - Test checks using the `npx checkly test` command. Pass environment variables with the `-e` flag, use `--record` to persist results, and use `--verbose` to see all errors.

packages/cli/src/ai-context/references/initialize.md

@@ -70,7 +70,25 @@ Run `npx checkly skills configure alert-channels` to access up-to-date informati
    - **next to the resource** — place the `check.ts` files next to page routes, api endpoints etc.
 
 
-#### Step 3 — Create the config file
+#### Step 3 — Check your account plan
+
+Before writing checks, verify what your account can do:
+
+```bash
+npx checkly account plan --output json
+```
+
+This shows your entitlements, limits, and available locations. Use this data when creating the config:
+
+- **Only use locations** from `locations.all` where `available` is `true`. Using unavailable locations will cause deploy failures.
+- **Check feature availability** before configuring constructs like private locations, advanced alert channels, or higher-frequency schedules.
+- **Respect metered limits** — the `quantity` field shows maximums for each metered feature.
+
+If a feature the user wants is disabled, the response includes an `upgradeUrl` — share it so they can upgrade their plan.
+
+Run `npx checkly skills manage plan` for the full reference.
+
+#### Step 4 — Create the config file
 
 Run the following command to retrieve the configure skill reference:
 
@@ -80,13 +98,13 @@ npx checkly skills configure
 
 Use the output to create a `checkly.config.ts` (or `checkly.config.js` if the user chose JavaScript) in the project root.
 
-Adjust the `checkMatch` property according to previous selection.
+Adjust the `checkMatch` property according to previous selection. Use only locations verified as available in the previous step.
 
 Present the generated configuration to the user and ask if it looks correct. Allow the user to make changes.
 
 Congratulate the user on completing the config. Now it's time to test the configuration and turn everything into monitoring!
 
-#### Step 4: Log in to Checkly CLI
+#### Step 5: Log in to Checkly CLI
 
 To use the Checkly CLI the user needs to be logged in. Run the following command:
 
@@ -101,7 +119,7 @@ If the user is NOT logged in, present two options:
 - **Option A: Interactive login** — The user runs `npx checkly login` themselves. This command opens a browser for OAuth authentication and cannot be completed by an AI agent. Tell the user to run the command, complete the browser flow, and let you know when they're done so you can re-run `npx checkly whoami` to verify.
 - **Option B: Environment variables (recommended for agentic / CI use)** — The user sets `CHECKLY_API_KEY` and `CHECKLY_ACCOUNT_ID` as environment variables. They can create an API key in the Checkly dashboard under **User Settings > API Keys**. Once both variables are set, re-run `npx checkly whoami` to verify.
 
-#### Step 5: Summarize and test the new monitoring configuration
+#### Step 6: Summarize and test the new monitoring configuration
 
 Read the generated `checkly.config.ts` (or `checkly.config.js`) and summarize the configured checks, locations, and frequencies.
 

packages/cli/src/ai-context/references/investigate-checks.md

@@ -37,6 +37,28 @@ npx checkly checks get <check-id> --result <result-id>
 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