{"id":17186,"library":"checkly","title":"Checkly CLI","description":"The Checkly CLI provides a JavaScript/TypeScript-native workflow for implementing \"monitoring as code,\" allowing developers to define, test, and deploy synthetic monitoring checks directly from their codebase. This approach integrates monitoring into the development pipeline, enabling version control, code reviews, and automated deployments. The current stable version is 7.12.0, with minor releases occurring frequently, often weekly or bi-weekly. Key differentiators include first-class support for `@playwright/test` for browser checks, a TypeScript-first design for robust type-checking and autocompletion, and the flexibility to run checks either on the Checkly cloud platform or within private locations on-premise, emphasizing a developer-centric experience.","status":"active","version":"7.12.0","language":"javascript","source_language":"en","source_url":"https://github.com/checkly/checkly-cli","tags":["javascript","typescript"],"install":[{"cmd":"npm install checkly","lang":"bash","label":"npm"},{"cmd":"yarn add checkly","lang":"bash","label":"yarn"},{"cmd":"pnpm add checkly","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency required for runtime code execution/transpilation of TypeScript check files.","package":"jiti","optional":false}],"imports":[{"note":"These symbols are used to define API monitoring checks programmatically. CommonJS 'require' syntax is not supported for these ESM-first constructs.","wrong":"const { ApiCheck, AssertionBuilder } = require('checkly/constructs')","symbol":"ApiCheck, AssertionBuilder","correct":"import { ApiCheck, AssertionBuilder } from 'checkly/constructs'"},{"note":"For browser checks, Checkly CLI leverages Playwright. 'test' and 'expect' are imported directly from '@playwright/test', which should be installed as a dev dependency in your project.","wrong":"import { test, expect } from 'checkly'","symbol":"test, expect","correct":"import { test, expect } from '@playwright/test'"},{"note":"The Checkly CLI is primarily interacted with via the `npx checkly` command-line interface. Direct programmatic import of CLI commands from the 'checkly' package for execution is not the intended usage for end-users.","wrong":"import { deploy } from 'checkly'","symbol":"(CLI Commands)","correct":"npx checkly <command>"}],"quickstart":{"code":"import { ApiCheck, AssertionBuilder } from 'checkly/constructs';\nimport { test, expect } from '@playwright/test';\nimport * as path from 'path';\n\n// --- API Check Example (api.check.ts) ---\n// Define an API check for a public endpoint.\nnew ApiCheck('books-api-check-1', {\n  name: 'Books API Status',\n  request: {\n    url: 'https://danube-web.shop/api/books',\n    method: 'GET',\n    assertions: [\n      AssertionBuilder.statusCode().equals(200),\n      AssertionBuilder.jsonBody('$[0].id').isNotNull(),\n    ],\n  },\n});\n\n// --- Browser Check Example (homepage.spec.ts) ---\n// Define a Playwright-based browser check for a homepage.\ntest('webshop homepage loads and has title', async ({ page }) => {\n  const response = await page.goto('https://danube-web.shop');\n  expect(response?.status()).toBeLessThan(400); // Expect a successful HTTP status code\n  await expect(page).toHaveTitle(/Danube WebShop/);\n\n  // Optionally take a screenshot upon successful load\n  const screenshotPath = path.join(process.cwd(), 'homepage.jpg');\n  await page.screenshot({ path: screenshotPath });\n  console.log(`Screenshot saved to: ${screenshotPath}`);\n});\n\n// To run these checks after saving them in your project (e.g., in `__checks__` directory):\n// 1. Install Checkly CLI and Playwright: `npm install --save-dev checkly @playwright/test`\n// 2. Log in to your Checkly account: `npx checkly login` (Requires a Checkly account)\n// 3. Run tests locally: `npx checkly test`\n// 4. Deploy checks to the Checkly cloud: `npx checkly deploy`","lang":"typescript","description":"This code defines a simple API check and a Playwright-based browser check for a webshop, demonstrating how to write monitoring as code. It includes instructions for local testing and deployment to the Checkly cloud via the CLI."},"warnings":[{"fix":"Upgrade your Node.js environment to a supported version (e.g., using `nvm install 20 && nvm use 20` or similar version manager).","message":"The Checkly CLI requires Node.js version 18.19.0 or greater, or 20.5.0 or greater. Older Node.js versions are not supported and will prevent the CLI from running correctly. Ensure your environment meets these engine requirements.","severity":"breaking","affected_versions":">=7.0.0"},{"fix":"For an easy setup, use `npm create checkly@latest`. If installing manually, ensure `npm install --save-dev jiti typescript` is run to satisfy peer dependencies and allow TypeScript transpilation.","message":"When defining checks in TypeScript, the CLI relies on a TypeScript loader (like 'jiti'). If you install the CLI manually (`npm install checkly`) instead of using `npm create checkly@latest`, you might need to ensure 'jiti' and 'typescript' are correctly installed and configured as peer dependencies.","severity":"gotcha","affected_versions":">=7.0.0"},{"fix":"Install Playwright: `npm install --save-dev @playwright/test`.","message":"Browser checks are written using `@playwright/test`. This package needs to be installed as a dev dependency in your project for browser checks to function correctly, even though Checkly CLI orchestrates their execution.","severity":"gotcha","affected_versions":">=7.0.0"},{"fix":"Run `npx skills add checkly/checkly-cli` to enable enhanced AI coding assistant features for Checkly CLI within supported AI environments.","message":"The Checkly CLI supports AI Agent capabilities, which can be extended by installing 'skills'. This functionality, introduced in v7.7.0, requires an additional `npx skills add checkly/checkly-cli` command to provide AI coding assistants with full context.","severity":"gotcha","affected_versions":">=7.7.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Ensure `jiti` and `typescript` are installed as `devDependencies` (`npm install --save-dev jiti typescript`) and that your `tsconfig.json` is correctly set up. Using `npm create checkly@latest` is recommended for initial setup.","cause":"The Checkly CLI could not find a suitable TypeScript loader to transpile your `.ts` check files, often due to missing 'jiti' or 'typescript' packages, or incorrect `tsconfig.json` configuration.","error":"Error: TypeScript loader is missing"},{"fix":"Install `jiti` explicitly: `npm install jiti` or `npm install --save-dev jiti`.","cause":"The `jiti` peer dependency, required by Checkly CLI for runtime transpilation, is missing from your project's `node_modules`.","error":"Error: Cannot find module 'jiti'"},{"fix":"Upgrade your Node.js environment to a supported version using a tool like `nvm` (e.g., `nvm install 20 && nvm use 20`).","cause":"Your current Node.js version does not meet the minimum requirements (`^18.19.0 || >=20.5.0`) specified by the `checkly` package's engine field.","error":"Node.js version not supported"}],"ecosystem":"npm","meta_description":null}