Intallation

Creating a CLI project from scratch

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 20.19+ or 22.12+.
• A text editor like Visual Studio Code.

Installation

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

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',
 }
})

JavaScript

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

const config = {
 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',
 }
}

module.exports = config;

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.

Direct download

If you cannot access the npm registry directly, you can also download the Checkly CLI via our CDN.

• MacOS / Darwin
• Windows
• Linux

The download is a zipped folder containing a full installation of the boilerplate example project. You will find the following files and folders:

• a checkly.config.ts file.
• a package.json file including the necessary Typescript dependencies.
• a node_modules directory with all dependencies pre-installed.
• a __checks__ folder with some example checks.

If you want to move the CLI and its constructs to a different, already existing Node.js project, just copy the full contents of the node_modules folder to your project and manually add a checkly.config.ts file.

Using a Proxy Server

The CLI respects the common HTTP_PROXY environment variable for any outbound traffic, like running npx checkly test or npx checkly deploy.

Terminal

HTTP_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