Add checks run for ordinary check sessions (#1418)

* feat: add checks run command

* test: update checks help expectation

* fix: preserve JSON output for unmatched checks

Author: thebiglabasky

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

@@ -57,7 +57,7 @@ describe('help', () => {
   alert-channels   List and inspect alert channels in your Checkly account.
   api              Make an authenticated HTTP request to the Checkly API.
   assets           List and download result assets.
-  checks           List and inspect checks in your Checkly account.
+  checks           List, inspect, and run checks in your Checkly account.
   destroy          Destroy your project with all its related resources.
   env              Manage Checkly environment variables.
   help             Display help for checkly.

packages/cli/package.json

@@ -78,7 +78,7 @@
         "description": "List and download result assets."
       },
       "checks": {
-        "description": "List and inspect checks in your Checkly account."
+        "description": "List, inspect, and run checks in your Checkly account."
       },
       "env": {
         "description": "Manage Checkly environment variables."

packages/cli/src/ai-context/__tests__/references.spec.ts

@@ -47,6 +47,9 @@ describe('AI context investigation references', () => {
   it('documents check result attempts and asset retrieval', async () => {
     const content = normalizeLineEndings(await readReference('investigate-checks.md'))
 
+    expect(content).toContain('npx checkly checks run --tags production')
+    expect(content).toContain('creates ordinary Check Sessions')
+    expect(content).toContain('Test Sessions do not update normal check health')
     expect(content).toContain('npx checkly checks get <check-id> --result <result-id> --include-attempts --output json')
     expect(content).toContain('"result": {}')
     expect(content).toContain('"attempts": []')

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

@@ -72,7 +72,7 @@ export const REFERENCES = [
 export const INVESTIGATE_REFERENCES = [
   {
     id: 'investigate-checks',
-    description: 'Inspect checks (`checks list`, `checks get`), retry attempts, result assets, and trigger on-demand runs',
+    description: 'Inspect checks (`checks list`, `checks get`), retry attempts, result assets, and run on-demand monitoring or test sessions',
   },
   {
     id: 'investigate-alerting',

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

@@ -146,11 +146,27 @@ Flags:
 
 Pass one or more check IDs as positional arguments to get stats for specific checks only.
 
-## Trigger checks
+## Run checks with normal monitoring behavior
+
+```bash
+npx checkly checks run --tags production
+npx checkly checks run --check-id <check-id>
+npx checkly checks run --tags critical,api --detach
+```
+
+`checks run` creates ordinary Check Sessions using the checks' deployed
+configuration and locations. These runs update check health and apply configured
+alerting rules. The command waits for completion by default; use `--detach` to
+schedule the runs and exit immediately.
+
+## Trigger a recorded test session
 
 ```bash
 npx checkly trigger --tags production
 npx checkly trigger --tags critical,api
 ```
 
-Triggers existing deployed checks by tag. Useful for on-demand verification.
+`trigger` runs deployed checks as a Test Session. Use it for CI verification or
+when you need Test Session options such as location, environment, or retry
+overrides. Test Sessions do not update normal check health or send configured
+monitoring alerts.

packages/cli/src/commands/__tests__/checks-run.spec.ts

@@ -0,0 +1,231 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+import type { CheckSession, CompletedCheckSession } from '../../rest/check-sessions.js'
+
+vi.mock('../../rest/api.js', () => ({
+  checkSessions: {
+    trigger: vi.fn(),
+    pollUntilComplete: vi.fn(),
+  },
+}))
+
+import * as api from '../../rest/api.js'
+import {
+  CheckSessionWaitTimeoutError,
+  NoMatchingChecksError,
+} from '../../rest/check-sessions.js'
+import ChecksRun from '../checks/run.js'
+
+const pendingSessions: CheckSession[] = [
+  {
+    checkSessionId: '8166fa86-c9b4-4162-8541-d380c6c212d8',
+    checkSessionLink: 'https://app.checklyhq.com/check-sessions/8166fa86-c9b4-4162-8541-d380c6c212d8',
+    checkId: 'a4cd4ad9-4815-4a9e-92d2-0a7c562ee69a',
+    checkType: 'API',
+    name: 'Production API',
+    status: 'PROGRESS',
+    startedAt: '2026-07-21T12:00:00.000Z',
+    stoppedAt: null,
+    timeElapsed: 0,
+    runLocations: ['us-east-1'],
+    runSource: 'TRIGGER_API',
+  },
+  {
+    checkSessionId: '16e22c0d-22a5-4d03-93c5-91bc38ac3c85',
+    checkSessionLink: 'https://app.checklyhq.com/check-sessions/16e22c0d-22a5-4d03-93c5-91bc38ac3c85',
+    checkId: '22336fd1-c407-4bf7-a793-91c2246fd08f',
+    checkType: 'BROWSER',
+    name: 'Checkout journey',
+    status: 'PROGRESS',
+    startedAt: '2026-07-21T12:00:00.000Z',
+    stoppedAt: null,
+    timeElapsed: 0,
+    runLocations: ['eu-west-1'],
+    runSource: 'TRIGGER_API',
+  },
+]
+
+const completedSessions: CompletedCheckSession[] = pendingSessions.map((session, index) => ({
+  ...session,
+  status: index === 0 ? 'PASSED' : 'DEGRADED',
+  stoppedAt: '2026-07-21T12:00:01.000Z',
+  timeElapsed: 1_000,
+  results: [],
+}))
+
+function defaultFlags (overrides: Record<string, unknown> = {}) {
+  return {
+    'tags': undefined,
+    'check-id': undefined,
+    'refresh-cache': false,
+    'timeout': 600,
+    'detach': false,
+    'fail-on-no-matching': true,
+    'output': 'table',
+    ...overrides,
+  }
+}
+
+function createCommandContext (flags: Record<string, unknown>) {
+  const logged: string[] = []
+  return {
+    parse: vi.fn().mockResolvedValue({ flags }),
+    error: vi.fn((message: string) => {
+      throw new Error(message)
+    }),
+    log: vi.fn((message?: string) => {
+      if (message) logged.push(message)
+    }),
+    style: {
+      outputFormat: undefined,
+      actionStart: vi.fn(),
+      actionStatus: vi.fn(),
+      actionSuccess: vi.fn(),
+      actionFailure: vi.fn(),
+      longError: vi.fn(),
+    },
+    logged,
+  }
+}
+
+describe('checks run command', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    process.exitCode = undefined
+    vi.mocked(api.checkSessions.trigger).mockResolvedValue({ sessions: pendingSessions })
+    vi.mocked(api.checkSessions.pollUntilComplete)
+      .mockImplementation(id => Promise.resolve(completedSessions.find(session => session.checkSessionId === id)!))
+  })
+
+  it('maps selectors to the public check sessions API and waits by default', async () => {
+    const ctx = createCommandContext(defaultFlags({
+      'tags': ['production,api', 'critical'],
+      'check-id': [pendingSessions[0].checkId],
+      'refresh-cache': true,
+      'timeout': 120,
+    }))
+
+    await ChecksRun.prototype.run.call(ctx as any)
+
+    expect(api.checkSessions.trigger).toHaveBeenCalledWith({
+      target: {
+        matchTags: [['production', 'api'], ['critical']],
+        checkId: [pendingSessions[0].checkId],
+      },
+      refreshCache: true,
+    })
+    expect(api.checkSessions.pollUntilComplete).toHaveBeenCalledTimes(2)
+    expect(api.checkSessions.pollUntilComplete).toHaveBeenCalledWith(
+      pendingSessions[0].checkSessionId,
+      expect.any(Number),
+    )
+    expect(ctx.style.actionStart).toHaveBeenCalledWith('Waiting for check sessions to complete...')
+    expect(ctx.style.actionSuccess).toHaveBeenCalled()
+    expect(ctx.logged[0]).toContain('2 check sessions completed')
+    expect(process.exitCode).toBeUndefined()
+  })
+
+  it('omits the target when no selectors are provided', async () => {
+    const ctx = createCommandContext(defaultFlags({ detach: true }))
+
+    await ChecksRun.prototype.run.call(ctx as any)
+
+    expect(api.checkSessions.trigger).toHaveBeenCalledWith({ refreshCache: false })
+  })
+
+  it('detaches without requesting completion', async () => {
+    const ctx = createCommandContext(defaultFlags({ detach: true }))
+
+    await ChecksRun.prototype.run.call(ctx as any)
+
+    expect(api.checkSessions.pollUntilComplete).not.toHaveBeenCalled()
+    expect(ctx.style.actionStart).not.toHaveBeenCalled()
+    expect(ctx.logged[0]).toContain('2 check sessions started.')
+  })
+
+  it('prints a stable JSON envelope without spinner output', async () => {
+    const ctx = createCommandContext(defaultFlags({ output: 'json' }))
+
+    await ChecksRun.prototype.run.call(ctx as any)
+
+    expect(JSON.parse(ctx.logged[0])).toEqual({ sessions: completedSessions })
+    expect(ctx.style.actionStart).not.toHaveBeenCalled()
+  })
+
+  it.each(['FAILED', 'TIMED_OUT', 'CANCELLED'] as const)('exits 1 when a session is %s', async status => {
+    vi.mocked(api.checkSessions.pollUntilComplete).mockResolvedValue({
+      ...completedSessions[0],
+      status,
+    })
+    vi.mocked(api.checkSessions.trigger).mockResolvedValue({ sessions: [pendingSessions[0]] })
+    const ctx = createCommandContext(defaultFlags())
+
+    await ChecksRun.prototype.run.call(ctx as any)
+
+    expect(process.exitCode).toBe(1)
+  })
+
+  it('fails by default when no checks match', async () => {
+    vi.mocked(api.checkSessions.trigger).mockRejectedValue(new NoMatchingChecksError())
+    const ctx = createCommandContext(defaultFlags())
+
+    await ChecksRun.prototype.run.call(ctx as any)
+
+    expect(ctx.logged).toContain('No matching checks were found.')
+    expect(process.exitCode).toBe(1)
+  })
+
+  it('can succeed when no checks match', async () => {
+    vi.mocked(api.checkSessions.trigger).mockRejectedValue(new NoMatchingChecksError())
+    const ctx = createCommandContext(defaultFlags({ 'fail-on-no-matching': false }))
+
+    await ChecksRun.prototype.run.call(ctx as any)
+
+    expect(process.exitCode).toBeUndefined()
+  })
+
+  it('prints an empty JSON envelope when no checks match without failing', async () => {
+    vi.mocked(api.checkSessions.trigger).mockRejectedValue(new NoMatchingChecksError())
+    const ctx = createCommandContext(defaultFlags({
+      'fail-on-no-matching': false,
+      'output': 'json',
+    }))
+
+    await ChecksRun.prototype.run.call(ctx as any)
+
+    expect(ctx.logged).toHaveLength(1)
+    expect(JSON.parse(ctx.logged[0])).toEqual({ sessions: [] })
+    expect(process.exitCode).toBeUndefined()
+  })
+
+  it('reports an overall completion timeout and leaves sessions running', async () => {
+    vi.mocked(api.checkSessions.trigger).mockResolvedValue({ sessions: [pendingSessions[0]] })
+    vi.mocked(api.checkSessions.pollUntilComplete)
+      .mockRejectedValue(new CheckSessionWaitTimeoutError(pendingSessions[0].checkSessionId))
+    const ctx = createCommandContext(defaultFlags())
+
+    await ChecksRun.prototype.run.call(ctx as any)
+
+    expect(ctx.style.actionFailure).toHaveBeenCalled()
+    expect(ctx.style.longError).toHaveBeenCalledWith(
+      'Timed out waiting for check sessions.',
+      expect.stringContaining('--detach'),
+    )
+    expect(process.exitCode).toBe(1)
+  })
+
+  it('rejects a non-positive timeout before scheduling', async () => {
+    const ctx = createCommandContext(defaultFlags({ timeout: 0 }))
+
+    await expect(ChecksRun.prototype.run.call(ctx as any))
+      .rejects
+      .toThrow('--timeout must be an integer greater than 0.')
+    expect(api.checkSessions.trigger).not.toHaveBeenCalled()
+  })
+
+  it('has intentional command metadata', () => {
+    expect(ChecksRun.readOnly).toBe(false)
+    expect(ChecksRun.destructive).toBe(false)
+    expect(ChecksRun.idempotent).toBe(false)
+  })
+})

packages/cli/src/commands/__tests__/command-metadata.spec.ts

@@ -5,6 +5,7 @@ import { BaseCommand } from '../baseCommand.js'
 import ChecksList from '../checks/list.js'
 import ChecksGet from '../checks/get.js'
 import ChecksStats from '../checks/stats.js'
+import ChecksRun from '../checks/run.js'
 import StatusPagesList from '../status-pages/list.js'
 import StatusPagesGet from '../status-pages/get.js'
 import AlertChannelsList from '../alert-channels/list.js'
@@ -62,6 +63,7 @@ const commands: Array<[string, typeof BaseCommand]> = [
   ['checks list', ChecksList],
   ['checks get', ChecksGet],
   ['checks stats', ChecksStats],
+  ['checks run', ChecksRun],
   ['status-pages list', StatusPagesList],
   ['status-pages get', StatusPagesGet],
   ['test-sessions list', TestSessionsList],