Installation

To kickstart a new project with the CLI, we recommend running npx checkly init. But you can also add the CLI from scratch with the following steps.

Prerequisites

Node.js 22.13+.
A text editor like Visual Studio Code.

First, install the CLI.

Terminal

npm i --save-dev checkly

Built-in TypeScript support requires Checkly CLI v8 or later. On earlier versions, also install a TypeScript loader with npm install --save-dev jiti (preferred) or npm install --save-dev ts-node typescript.

Create a minimal checkly.config.ts (or checkly.config.js) at the root of your project. We recommend using TypeScript.

TypeScript
JavaScript

import { defineConfig } from 'checkly'
import { Frequency } from 'checkly/constructs'

export default defineConfig({
 projectName: 'Website Monitoring',
 logicalId: 'website-monitoring-1',
 repoUrl: 'https://github.com/acme/website',
 checks: {
   activated: true,
   muted: false,
   runtimeId: '2025.04',
   frequency: Frequency.EVERY_5M,
   locations: ['us-east-1', 'eu-central-1'],
   tags: ['website', 'api'],
   checkMatch: '**/__checks__/**/*.check.ts',
   ignoreDirectoriesMatch: [],
   browserChecks: {
     frequency: Frequency.EVERY_10M,
     testMatch: '**/__checks__/**/*.spec.ts',
   },
 },
 cli: {
   runLocation: 'eu-central-1',
 }
})

const { defineConfig } = require('checkly')
const { Frequency } = require('checkly/constructs')

module.exports = defineConfig({
 projectName: 'Website Monitoring',
 logicalId: 'website-monitoring-1',
 repoUrl: 'https://github.com/acme/website',
 checks: {
   activated: true,
   muted: false,
   runtimeId: '2025.04',
   frequency: Frequency.EVERY_5M,
   locations: ['us-east-1', 'eu-central-1'],
   tags: ['website', 'api'],
   checkMatch: '**/__checks__/**/*.check.js',
   ignoreDirectoriesMatch: [],
   browserChecks: {
     frequency: Frequency.EVERY_10M,
     testMatch: '**/__checks__/**/*.spec.js',
   },
 },
 cli: {
   runLocation: 'eu-central-1',
 }
})

Use the CLI to authenticate and pick a Checkly account. Make sure you have signed up for a free account on checklyhq.com before hand or just sign up for a new account straight from the terminal.

Terminal

npx checkly login

Global installs and `npx checkly@<version>`

Run the CLI through npx checkly from your project (or your package manager’s equivalent, such as pnpm exec checkly or yarn checkly), so the CLI version is the one in your package.json. Your checks only load with the checkly package your project installs, because they register with that copy. Since CLI version 10.0.0, when you run checkly from any other installation, for example a global npm i -g checkly, pnpm dlx checkly or npx checkly@<version>, inside a project that has its own checkly package, the CLI hands the command to your project’s installation, as npx checkly or its equivalent would. This applies to every command. The CLI looks for your project’s installation from the directory of the --config file if you pass one, and from the current directory otherwise. If the two versions differ, the CLI says which version runs. To use another version, install that version in your project. Set CHECKLY_NO_DELEGATION=1 to turn off the hand-off. Older global installs, and any install with the hand-off turned off, fail on projects that have their own checkly package with Unable to create a construct ... outside a Checkly CLI project.

Using a Proxy Server

The CLI respects the common proxy environment variables for any outbound traffic, like running npx checkly test or npx checkly deploy. Because the CLI connects over HTTPS, set HTTPS_PROXY (or ALL_PROXY). HTTP_PROXY alone isn’t used for these connections. Use NO_PROXY to bypass the proxy for specific hosts.

Terminal

HTTPS_PROXY=https://proxy-url npx checkly test

The CLI communicates with the following domains if you need to allow-list them in your proxy:

api.checklyhq.com
events.checklyhq.com

Getting Started

CLI Commands

Installation

Prerequisites

Installation

Global installs and `npx checkly@<version>`

Using a Proxy Server

​Prerequisites

​Installation

​Global installs and npx checkly@<version>

​Using a Proxy Server

Prerequisites

Installation

Global installs and `npx checkly@<version>`

Using a Proxy Server