Skip to content

About

TS/JS native Monitoring as Code workflow

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

97 stars

Watchers

8 watching

Forks

The Checkly CLI gives you a JavaScript/TypeScript-native workflow for coding, testing and deploying synthetic monitoring at scale, from your code base. We call this workflow monitoring as code (MaC).

  • Codeable, testable, reviewable monitoring constructs. Works with your dev pipeline. From your IDE, via PR to CI.
  • Native @playwright/test support. No lock-in, just write standard *.spec.ts files.
  • Alerting baked in. Set alerts for Slack, SMS and many more channels.
  • Typescript-first. Fully typed for easy refactoring and code completion.
  • Run in the cloud or on-prem. Run on the Checkly cloud or in your network using the Private Locations

A quick example

Monitoring checks are written by instantiating constructs from the checkly/constructs package...

// books-api.check.ts
import { ApiCheck, AssertionBuilder } from 'checkly/constructs'

new ApiCheck('books-api-check-1', {
  name: 'Books API',
  request: {
    url: 'https://danube-web.shop/api/books',
    method: 'GET',
    assertions: [
      AssertionBuilder.statusCode().equals(200),
      AssertionBuilder.jsonBody('$[0].id').isNotNull(),
    ],
  }
})

For browser checks, you can just write standard *.spec.ts files using @playwright/test.

// home.spec.ts
import { test, expect } from '@playwright/test'

test('webshop homepage', async ({ page }) => {
  const response = await page.goto('https://danube-web.shop')
  expect(response?.status()).toBeLessThan(400)
  await expect(page).toHaveTitle(/Danube WebShop/)
  await page.screenshot({ path: 'homepage.jpg' })
})

Run your checks from your local machine or in CI using npx checkly test

npx checkly test
Parsing your project... done

Running 2 checks in eu-west-1.

__checks__/books-api.check.ts
  ✔ Books API 1 (52ms)
__checks__/home.spec.ts
  ✔ home.spec.ts (5s)

2 passed, 2 total

Now deploy your checks to the Checkly cloud so they can monitor your apps and APIs around the clock and alert you when things break.

npx checkly deploy

Parsing your project... done
Successfully deployed project "Acme webapp" to account "Acme Production".

Installation

First, make sure you sign up for a free Checkly account or signup via the terminal using npx checkly login.

Then, the easiest way to get started is to install the CLI using the following command:

npm create checkly@latest

This command will guide you through some simple steps and set up a fully working example project for you. Should take ~1 minute.

You can also set up the CLI from scratch by running:

npm install --save-dev checkly

Docs

Official docs are over at checklyhq.com/docs/cli

Account usage in v10

Migration from v9:

  • Summary JSON renames totals.credits.used to totals.creditsUsed and removes totals.credits.percentOfBudget and embedded projections. Get forecasts with checkly account usage projections <id>.
  • Summary and series expose usageTermsIds instead of usageTermsId. Series replaces warnings with coverage.gaps.
  • Terms and series JSON use { data, pagination: { nextId, length } }. Terms default to table output; use term <id> for detail.
  • --from and --to bound an inclusive UTC range. On terms, they select overlapping contracts rather than one contract covering --to.
  • --check-type is removed. Use --pricing-rule to select charges or series --group-by checkType for a check-type breakdown.

AI Agents & Coding Assistants

The Checkly CLI is designed with AI-powered development in mind. With Monitoring as Code, your entire monitoring setup lives in TypeScript files — perfect for AI agents that can read, write, and reason about code.

To give your AI coding assistant full context about the Checkly CLI, install the Checkly skill:

npx skills add checkly/checkly-cli

This provides your AI with documentation, best practices, and examples so it can help you create and manage API checks, browser checks, alert channels, and more.

Check out our AI Agents & Coding Assistants docs for more best practices and examples.

Error reporting

When the CLI crashes because of a bug in its own code, it sends one report about the crash to Checkly, so we can find and fix the bug. Only crashes inside the CLI's own files are reported (a TypeError, ReferenceError or RangeError). Errors in your own code, failed checks, API errors and network problems are never reported. Invalid configuration is normally shown as a clear message and not reported; if it makes the CLI crash instead, that crash is reported, because the CLI should have caught the mistake.

A report contains:

  • the error type, its message and the stack trace; paths in the CLI's own files are shortened to the file inside the CLI (for example checkly/dist/commands/deploy.js), paths in any installed package, including your own packages, start at node_modules/, and every other path in the stack trace is replaced with a placeholder
  • the CLI version, the command name (for example deploy), and whether the CLI runs in a terminal, in CI or for an AI agent
  • your operating system, CPU architecture and Node.js version

The message is sent as it is, with two exceptions. The CLI removes Checkly API keys, Bearer and Basic tokens and user names and passwords in URLs. It replaces the paths of the CLI's folder, the folder you run the CLI from and your home folder with placeholders.

To turn error reporting off, set either environment variable:

export CHECKLY_NO_ERROR_REPORTING=1
# or the cross-tool convention
export DO_NOT_TRACK=1

Need help?

Local Development

Set the CHECKLY_E2E_CLI_VERSION environment variable to override the version the CLI reports to the Checkly API (the x-checkly-cli-version header). It is an e2e/local-development hook only and does not change which CLI version runs.

To get started with local development check CONTRIBUTING.MD

About

TS/JS native Monitoring as Code workflow

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

97 stars

Watchers

8 watching

Forks

Releases

Used by

Contributors

Languages