Checkly CLI Skills

Checkly CLI Skills

Comprehensive Checkly CLI command reference and Monitoring as Code (MaC) workflows.

Quick start

# Create new Checkly project
npm create checkly@latest

# Test checks locally
npx checkly test

# Deploy to Checkly cloud
npx checkly deploy

# Inspect Checkly's bundled CLI agent references when needed
npx checkly skills

What is Monitoring as Code?

The Checkly CLI provides a TypeScript/JavaScript-native workflow for coding, testing, and deploying synthetic monitoring at scale. Define your monitoring checks as code, test them locally, version control them with Git, and deploy through CI/CD pipelines.

Key benefits:

• Codeable - Define checks in TypeScript/JavaScript
• Testable - Run checks locally before deployment
• Reviewable - Code review your monitoring in PRs
• Native Playwright - Use standard @playwright/test specs
• CI/CD Native - Integrate with your deployment pipeline

Skill organization

This skill routes to specialized sub-skills by Checkly domain:

Getting Started:

• checkly-auth - Authentication setup and login
• checkly-config - Configuration files (checkly.config.ts) and project structure
• checkly-members - Account member and pending-invite listing, role updates, and removals

Core Workflows:

• checkly-test - Local testing workflow with npx checkly test
• checkly-deploy - Deployment to Checkly cloud
• checkly-import - Import existing checks from Checkly to code

Check Types:

• checkly-checks - API checks, browser checks, multi-step checks
• checkly-monitors - Heartbeat, TCP, DNS, URL, gRPC, SSL, and traceroute monitors
• checkly-groups - Check groups for organization and shared config

Advanced:

• checkly-constructs - Constructs system and resource management
• checkly-playwright - Playwright test suites and configuration
• checkly-advanced - Retry strategies, reporters, environment variables, bundling

Operations:

• checkly-members - Audit and manage Checkly account access with npx checkly members
• checkly-test - Also covers npx checkly test-sessions for recorded test-session drilldown and RCA context
• checkly-checks - Inspect, run, and delete deployed checks with npx checkly checks; confirm live-run targets before checks run, and use checks delete --dry-run before destructive deletes
• checkly-assets - List/download result assets such as logs, traces, videos, screenshots, pcap, reports, and files for failure investigation

When to use Checkly CLI vs Web UI

Use Checkly CLI when:

• Defining monitoring as part of your codebase
• Automating check creation/updates in CI/CD
• Testing checks locally during development
• Version controlling monitoring configuration
• Managing multiple checks efficiently
• Integrating monitoring with application deployments

Use Web UI when:

• Exploring Checkly for the first time
• Viewing dashboards and historical results
• Analyzing check failures and incidents
• Managing account-level settings
• Configuring alert channels (email, Slack App, PagerDuty)
• Setting up private locations

Common workflows

New project setup

# Initialize project
npm create checkly@latest
cd my-checkly-project

# Authenticate
npx checkly login

# Test locally
npx checkly test

# Deploy to cloud
npx checkly deploy

Daily development

# Create new API check
cat > __checks__/api-status.check.ts <<'EOF'
import { ApiCheck, AssertionBuilder } from 'checkly/constructs'

new ApiCheck('api-status-check', {
  name: 'API Status Check',
  request: {
    url: 'https://api.example.com/status',
    method: 'GET',
    assertions: [
      AssertionBuilder.statusCode().equals(200),
      AssertionBuilder.responseTime().lessThan(500),
    ],
  },
})
EOF

# Test locally
npx checkly test

# Deploy when ready
npx checkly deploy

Browser check with Playwright

# Create browser check
cat > __checks__/homepage.spec.ts <<'EOF'
import { test, expect } from '@playwright/test'

test('homepage loads', async ({ page }) => {
  const response = await page.goto('https://example.com')
  expect(response?.status()).toBeLessThan(400)
  await expect(page).toHaveTitle(/Example/)
  await page.screenshot({ path: 'homepage.jpg' })
})
EOF

# Test with Playwright locally (faster)
npx playwright test __checks__/homepage.spec.ts

# Test via Checkly runtime
npx checkly test __checks__/homepage.spec.ts

# Deploy
npx checkly deploy

Import existing checks

# Preview generated code without creating a plan
npx checkly import --preview

# Create the plan and generated code
npx checkly import plan

# Review generated code
git diff

# Apply one reviewed plan, but keep it pending during PR review
npx checkly import apply --plan-id <plan-id> --no-commit

# After the generated code is merged into the deployment branch, preview commit
npx checkly import commit --plan-id <plan-id> --dry-run

Do not deploy generated import code before applying its plan: that can create duplicate resources. Keep the applied plan pending until the generated code is durable, then commit it through the confirmation protocol in checkly-import.

Agent-mode confirmation protocol

Write commands such as deploy, destroy, import commit, and import cancel return exit code 2 with status: "confirmation_required" in agent mode. Present the returned changes to the user, then run the returned confirmCommand verbatim only after explicit approval. Do not append --force yourself, remove flags that appear in the returned command, or assume parser-default flags are user intent.

Inspect deployed check failures

# List failing checks
npx checkly checks list --status failing

# Inspect a deployed check and recent runs
npx checkly checks get <check-id>
npx checkly checks get <check-id> --output json

# Drill into an error group or specific result
npx checkly checks get <check-id> --error-group <error-group-id>
npx checkly checks get <check-id> --result <result-id>

When investigating a deployed failure, look for errorGroups, rootCause, or RCA fields in the output. If Checkly already surfaced Rocky AI root-cause analysis, reuse that context before suggesting additional debugging steps.

To trigger deployed checks rather than test local project definitions, route to checkly-checks for npx checkly checks run. This creates live check sessions using deployed locations and alerting rules, so confirm the intended check IDs or tags before running it; omitting selectors targets all deployed checks.

For alerting questions, use read-only JSON/API evidence before table output:

npx checkly checks get <check-id> --output json
npx checkly api /v1/checks/<check-id>
npx checkly alert-channels list --output json --limit 100

Only fetch alert-channel details for channel IDs referenced by the selected check or matching group. If the check has a groupId, inspect groups once with npx checkly api /v1/check-groups and locate the matching group. Do not probe guessed account/global alerting endpoints; if output only shows useGlobalAlertSettings: true, say global alert settings are selected but their policy details were not available in the inspected CLI/API output.

Decision Trees

"What type of check should I create?"

What are you monitoring?
├─ REST API / HTTP endpoint
│  ├─ Simple availability → API Check (request + status assertion)
│  ├─ Complex validation → API Check (request + multiple assertions + scripts)
│  └─ Just uptime/ping → URL Monitor (simpler, faster)
│
├─ Web application / User flow
│  ├─ Single page → Browser Check (one .spec.ts file)
│  ├─ Multiple steps → Browser Check or Multi-Step Check
│  └─ Full test suite → Playwright Check Suite (playwright.config.ts)
│
└─ Service health / Infrastructure
   ├─ Periodic heartbeat → Heartbeat Monitor
   ├─ TCP port → TCP Monitor
   ├─ DNS record → DNS Monitor
   ├─ Simple HTTP → URL Monitor
   ├─ gRPC method / health service → gRPC Monitor
   ├─ Certificate / TLS posture → SSL Monitor
   └─ Network path / packet loss → Traceroute Monitor

Quick reference:

• API Check: HTTP requests with assertions (status, headers, body, response time)
• Browser Check: Single Playwright spec file for web testing
• Multi-Step Check: Complex browser workflows (legacy, use Browser Check instead)
• Playwright Check Suite: Multiple Playwright tests with projects/parallelization
• Monitors: Simple health checks without code execution

"Test locally or deploy?"

What stage are you at?
├─ Developing new check
│  ├─ Browser check → npx playwright test (fastest iteration)
│  └─ API check → npx checkly test (includes assertions)
│
├─ Ready to validate
│  └─ npx checkly test (runs in Checkly runtime, catches issues)
│
└─ Ready for production
   └─ npx checkly deploy (schedule checks to run continuously)

Testing hierarchy:

1. npx playwright test - Fastest, local Playwright execution (browser checks only)
2. npx checkly test - Validates in Checkly runtime, catches compatibility issues
3. npx checkly deploy - Deploys for continuous scheduled monitoring

"File-based or construct-based checks?"

How do you want to define checks?
├─ Auto-discovery (convention over configuration)
│  ├─ Browser checks → *.spec.ts files matching testMatch pattern
│  ├─ Multi-step → *.check.ts files with MultiStepCheck construct
│  └─ API checks → *.check.ts files with ApiCheck construct
│
└─ Explicit definition
   ├─ Programmatic → Construct instances in .check.ts files
   └─ Full control → Playwright Check Suite with playwright.config.ts

Patterns:

• Auto-discovery: Configure checks.browserChecks.testMatch in checkly.config.ts
• Explicit constructs: Import from checkly/constructs and instantiate
• Playwright projects: Define multiple test suites with different configs

"Where should configuration go?"

What are you configuring?
├─ Project-level (all checks)
│  └─ checkly.config.ts → defaults, locations, frequency, runtime
│
├─ Group-level (related checks)
│  └─ CheckGroup construct → shared settings for subset of checks
│
└─ Check-level (individual)
   └─ Check constructor → override defaults for specific check

Configuration hierarchy (specific overrides general):

1. Check-level properties (highest priority)
2. CheckGroup properties
3. checkly.config.ts defaults
4. Checkly account defaults (lowest priority)

Project structure

Typical Checkly CLI project:

my-monitoring-project/
├── checkly.config.ts          # Project configuration
├── __checks__/                # Check definitions
│   ├── api.check.ts           # API check construct
│   ├── homepage.spec.ts       # Browser check (auto-discovered)
│   ├── login.spec.ts          # Another browser check
│   └── utils/
│       ├── alert-channels.ts  # Shared alert channel definitions
│       └── helpers.ts         # Shared helper functions
├── playwright.config.ts       # Playwright configuration (optional)
├── package.json
└── node_modules/
    └── checkly/               # CLI package with constructs

Checkly bundled agent references

npx checkly rules is deprecated; use npx checkly skills instead when you need Checkly's bundled AI-agent documentation, actions, or reference snippets:

npx checkly skills
npx checkly skills configure
npx checkly skills configure api-checks
npx checkly skills install

This repository is an external multi-skill package for agent clients. Do not rely on the deprecated checkly rules command when refreshing or installing these skills.

Installation methods

New project (recommended)

npm create checkly@latest

Creates scaffolded project with:

• checkly.config.ts with sensible defaults
• Example checks in __checks__/ directory
• package.json with checkly dependency
• .gitignore configured

Existing project

# Install as dev dependency
npm install --save-dev checkly

# Create configuration file
npx checkly init

Global installation (not recommended)

npm install -g checkly
checkly test

Note: Use npx checkly instead for project-specific CLI version.

Related Skills

Getting started:

• See checkly-auth for authentication setup
• See checkly-config for project configuration
• See checkly-test for local testing workflow

Creating checks:

• See checkly-checks for API and browser checks
• See checkly-monitors for simpler health checks
• See checkly-playwright for full test suite setup

Advanced workflows:

• See checkly-deploy for deployment strategies
• See checkly-constructs for understanding the object model
• See checkly-advanced for retry strategies and reporters

Import existing:

• See checkly-import to migrate from web UI to code