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

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:

Skill organization

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

Getting Started:

Core Workflows:

Check Types:

Advanced:

When to use Checkly CLI vs Web UI

Use Checkly CLI when:

Use Web UI when:

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

# Import all checks from Checkly account
npx checkly import plan
Review generated code
git diff
Commit imported checks
git add .
git commit -m "Import existing monitoring checks"

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

Quick reference:

"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:

"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

Installation methods

New project (recommended)

npm create checkly@latest

Creates scaffolded project with:

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:

Creating checks:

Advanced workflows:

Import existing:

# Create new Checkly project
npm create checkly@latest
Test checks locally
npx checkly test
Deploy to Checkly cloud
npx checkly deploy