Table of contents

Installing the Checkly CLI

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

• Node.js v16.x or higher.
• A text editor like Visual Studio Code.

First, install the CLI.

npm i --save-dev checkly

To use TypeScript, also install ts-node and typescript:

npm i --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.

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: '2022.10',
   frequency: Frequency.EVERY_5M,
   locations: ['us-east-1', 'eu-west-1'],
   tags: ['website', 'api'],
   checkMatch: '**/__checks__/**/*.check.ts',
   ignoreDirectoriesMatch: [],
   browserChecks: {
     frequency: Frequency.EVERY_10M,
     testMatch: '**/__checks__/**/*.spec.ts',
   },
 },
 cli: {
   runLocation: 'eu-west-1',
 }
})

const config = {
 projectName: 'Website Monitoring',
 logicalId: 'website-monitoring-1',
 repoUrl: 'https://github.com/acme/website',
 checks: {
   activated: true,
   muted: false,
   runtimeId: '2022.10',
   frequency: Frequency.EVERY_5M,
   locations: ['us-east-1', 'eu-west-1'],
   tags: ['website', 'api'],
   checkMatch: '**/__checks__/**/*.check.js',
   ignoreDirectoriesMatch: [],
   browserChecks: {
     frequency: Frequency.EVERY_10M,
     testMatch: '**/__checks__/**/*.spec.js',
   },
 },
 cli: {
   runLocation: 'eu-west-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.

npx checkly login

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.

There are different ways to authenticate when using the CLI depending on the environment where you are running the CLI from.

When running the CLI interactively from your dev environment, just use the built-in login command. If you have multiple Checkly accounts, it will prompt which account you want to target

npx checkly login

Once authenticated, you can switch between accounts using

npx checkly switch

or quickly find out which account you are currently targeting with

npx checkly whoami

When running the CLI from your CI pipeline you will need to export two variables in the shell:

• CHECKLY_API_KEY
• CHECKLY_ACCOUNT_ID

Go to your Settings page in Checkly and grab a fresh API key from the API keys tab and your Account ID from the Account settings tab.

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

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

Getting started with the Checkly CLI Structuring your project in Checkly

Last updated on December 13, 2024. You can contribute to this documentation by editing this page on Github