Checkly CLI Skills
Comprehensive Checkly CLI command reference and Monitoring as Code workflows. Use when user mentions Checkly CLI, monitoring as code, synthetic monitoring, API checks, browser checks, Playwright testing, GitHub Check re-runs, gRPC/SSL/traceroute monitors, check deployment, account plans, entitlements, organization usage, credits, or npx checkly commands. Routes to specialized sub-skills for auth, config, checks, monitors, testing, deployment, imports, account plan and usage, constructs, and advanced patterns. Triggers on checkly, GitHub Check Re-run button, repository_dispatch, monitoring as code, synthetic monitoring, checkly cli, npx checkly.
Checkly CLI Skills
Comprehensive Checkly CLI command reference and Monitoring as Code (MaC) workflows.
The current Checkly CLI requires Node.js 22.13.0 or later. Verify node --version before install, init, test, or deploy workflows; upgrading only the project dependency does not bypass the CLI's host-runtime floor.
Process and output contract
For source-backed details on reporter streams, validation, crash reporting, and error diagnosis, read runtime contracts.
Commands return results on stdout and progress, warnings, human-readable errors, hints and prompts on stderr. Keep streams separate for JSON parsing. Exit codes: 0 success, 1 failure, 2 invalid flags/arguments, 3 confirmation required. A second Ctrl+C terminates with SIGINT (shell status 130).
Deploy plans by default and schedules no immediate checks unless --schedule-on-deploy is set. No-change plans need no confirmation. test and pw-test fail on an empty selection; only test --no-fail-on-no-matching opts out. See checkly-deploy and checkly-test for the full contracts.
When no reporter is configured, CI and agent runs use ci, other runs use list. Jenkins, TeamCity and AWS CodeBuild are detected; CI=false, 0, no or off disables CI mode even on GitHub/GitLab hosts. Login/logout/switch/create-checkly prompt only when stdin and stderr are terminals: piping stdout preserves prompts, redirecting stderr disables them.
A global CLI, pnpm dlx checkly, or version-qualified npx checkly delegates to the project's installed CLI. A version mismatch prints which version actually runs. CHECKLY_NO_DELEGATION=1 opts out; a failed delegation warns and falls back to the invoking CLI. If construct creation reports two installations, align resolution and run the project dependency rather than mixing construct identities.
init can initialize an empty directory in CI/agent mode, including creating package.json. Agent output uses status: "success" or status: "error" with message; failures exit 1. api preserves binary bytes and JSON string/null responses; --jq requires JSON.
Choose CLI or MCP first
This skill pack drives npx checkly in a shell. Use the CLI for authoring, testing, importing, and deploying Monitoring as Code. Checkly MCP covers only a subset of live-account work: check status/results, test sessions, root-cause analysis, triggering deployed checks, and incidents.
Before the first command that talks to the Checkly API:
- With shell access, run
npx checkly whoamionce.- If it succeeds, continue with the CLI, even when Checkly MCP tools are also connected.
- If authentication fails, do not work around it for authoring, testing, imports, or deploys; authenticate with
npx checkly loginorCHECKLY_API_KEYplusCHECKLY_ACCOUNT_ID. - For supported live-account work only, an authenticated Checkly MCP connection may be used as a fallback. Call its
whoamitool first and name the account being used.
- Without shell access, use connected Checkly MCP tools only for their supported live-account operations. The MCP server cannot replace the CLI for Monitoring as Code.
Never mix CLI and MCP evidence without confirming that both sessions use the same account ID. A fallback write still requires the same explicit review/confirmation as the corresponding CLI action.
Run npx checkly skills before choosing a live CLI action. It loads the current action list locally and does not require Checkly authentication.
Quick start
# Create new Checkly project
npm create checkly@latest
# Test project checks in the Checkly runtime
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 logincheckly-config- Configuration files (checkly.config.ts) and project structurecheckly-members- Account member and pending-invite listing, role updates, and removalscheckly-usage- Account plan/entitlements plus organization contract terms, credit usage, projections, and grouped usage series
Core Workflows:
checkly-test- Local testing workflow with npx checkly testcheckly-deploy- Deployment to Checkly cloudcheckly-import- Import existing checks from Checkly to code
Check Types:
checkly-checks- API checks, browser checks, multi-step checkscheckly-monitors- Heartbeat, TCP, DNS, URL, gRPC, SSL, and traceroute monitorscheckly-groups- Check groups for organization and shared config
Advanced:
checkly-constructs- Constructs system and resource managementcheckly-playwright- Playwright test suites and configurationcheckly-advanced- Retry strategies, reporters, GitHub Check Re-run button and repository-dispatch handler setup, environment variables, bundling
Operations:
checkly-members- Audit and manage Checkly account access withnpx checkly memberscheckly-usage- Route account questions precisely:npx checkly account planfor plans, entitlements, feature limits, or private-location availability;npx checkly account usage terms/term/summary/series/projectionsfor organization contract credits and consumptioncheckly-test- Also coversnpx checkly test-sessionsfor recorded test-session drilldown and RCA contextcheckly-checks- Inspect, run, and delete deployed checks withnpx checkly checks; confirm live-run targets beforechecks run, and usechecks delete --dry-runbefore destructive deletescheckly-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 in the Checkly runtime
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 in the Checkly runtime
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 3 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.
If rca run reports Rocky AI is disabled for this account. (exit 1; JSON code: "ERR_ROCKY_AI_DISABLED"), an account owner must enable Rocky AI using the account-settings link in the error. Do not retry or edit checks to fix this account setting. This code identifies the disabled-feature condition, not every HTTP 403.
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 raw REST check payload has a non-null groupId, inspect groups once with npx checkly api /v1/check-groups and match that ID. Inspect returned doubleCheck and retryStrategy for retry behavior; removing groupId and doubleCheck from construct inputs did not remove those REST fields. 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; sequential API flows → Multi-Step Check
│ └─ Just uptime/ping → URL Monitor (simpler, faster)
│
├─ Web application / User flow
│ ├─ Single page → Browser Check (one .spec.ts file)
│ ├─ Multiple browser steps → Browser 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: Sequential API workflows using Playwright request APIs
- 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:
npx playwright test- Fastest, local Playwright execution (browser checks only)npx checkly test- Validates in Checkly runtime, catches compatibility issuesnpx 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.testMatchin checkly.config.ts - Explicit constructs: Import from
checkly/constructsand 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):
- Check-level properties (highest priority)
- CheckGroup properties
- checkly.config.ts defaults
- 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
Migration warning: checkly rules is removed and exits 127; 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. Use the bundled skills command when inspecting or installing upstream guidance. File read/write failures exit 1.
Installation methods
New project (recommended)
npm create checkly@latest
Creates scaffolded project with:
checkly.config.tswith sensible defaults- Example checks in
__checks__/directory package.jsonwith checkly dependency.gitignoreconfigured
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-authfor authentication setup - See
checkly-configfor project configuration - See
checkly-testfor local testing workflow - See
checkly-usagefor account plans, entitlements, contract credits, and usage reporting
Creating checks:
- See
checkly-checksfor API and browser checks - See
checkly-monitorsfor simpler health checks - See
checkly-playwrightfor full test suite setup
Advanced workflows:
- See
checkly-deployfor deployment strategies - See
checkly-constructsfor understanding the object model - See
checkly-advancedfor retry strategies, reporters, and opt-in GitHub Check re-runs
Import existing:
- See
checkly-importto migrate from web UI to code
- Downloads
- 3.5kAll time
- Security audit
- Review
- Last updated
- 4d ago
- Current version
- v1.0.22
- License
- MIT-0
