Skip to content

initialize.md

Latest commit

 

History

History
125 lines (74 loc) · 5.4 KB

initialize.md

File metadata and controls

125 lines (74 loc) · 5.4 KB
Raw

Checkly Project Setup

Follow these steps in order to set up a new Checkly monitoring project.

Step 0 — Pre-flight checks

Before starting, verify:

  1. Node.js is installed (node --version). Checkly CLI requires Node.js 18 or later.
  2. npm is available (npm --version).
  3. The current working directory is the right location for the project (or create/navigate to it).

If any pre-flight check fails, help the user fix it before proceeding.

Step 1 — Choose a setup method

Ask the user which setup method they prefer:

  • Option A: Initialize with CLI — Run npx checkly init to set up Checkly in the project. The CLI handles skill installation, dependencies, configuration, and optionally creates demo checks. This is the fastest way to get started.
  • Option B: AI-first — Generate the project structure and checks from scratch using this skill. Best when the user already knows what they want to monitor and prefers a tailored setup.

Option A: Initialize with CLI

Run the following command:

npx checkly init

The CLI will guide you through skill installation, configuration, and dependency setup. Once finished, setup is complete.

Option B: AI-first

Continue with the following steps:

Step 1: Install dependencies

Install the Checkly dependency

Check if npx checkly --version works. If not, run npm install --save-dev checkly.

Step 2: Gather the project requirements

Ask the user the following questions to determine the setup:

  1. What do you want to monitor? (multiple selections allowed)

    • Uptime monitoring — Monitor URLs for availability and response times
    • API checks — Validate API endpoints with custom assertions
    • Browser checks — Run Playwright scripts to test user flows
    • Multistep API checks — Chain multiple API requests into a single check
    • Playwright Check Suites — Reuse your existing Playwright project for synthetic monitoring

    Remember the selection for later steps when creating checks.

  2. How do you want to get alerted? (multiple selections allowed)

Run npx checkly skills configure alert-channels to access up-to-date information on alert channel options and setup.

  1. Where do you want to store your monitoring configuration?
    • checks — create all resources and check.ts files in a separate __checks__ directory
    • next to the resource — place the check.ts files next to page routes, api endpoints etc.

Step 3 — Check your account plan

Before writing checks, verify what your account can do:

npx checkly account plan --output json

This shows your entitlements, limits, and available locations. Use this data when creating the config:

  • Only use locations from locations.all where available is true. Using unavailable locations will cause deploy failures.
  • Check feature availability before configuring constructs like private locations, advanced alert channels, or higher-frequency schedules.
  • Respect metered limits — the quantity field shows maximums for each metered feature.

If a feature the user wants is disabled, the response includes an upgradeUrl — share it so they can upgrade their plan.

Run npx checkly skills manage plan for the full reference.

Step 4 — Create the config file

Run the following command to retrieve the configure skill reference:

npx checkly skills configure

Use the output to create a checkly.config.ts (or checkly.config.js if the user chose JavaScript) in the project root.

Adjust the checkMatch property according to previous selection. Use only locations verified as available in the previous step.

Present the generated configuration to the user and ask if it looks correct. Allow the user to make changes.

Congratulate the user on completing the config. Now it's time to test the configuration and turn everything into monitoring!

Step 5: Log in to Checkly CLI

To use the Checkly CLI the user needs to be logged in. Run the following command:

npx checkly whoami

If the user is logged in, verify the information and if it's the correct account.

If the user is NOT logged in, present two options (lead with env vars — they work for agents, CI, and interactive use):

  • Option A: Environment variables (recommended) — The user sets CHECKLY_API_KEY and CHECKLY_ACCOUNT_ID as environment variables. They can create an API key at https://app.checklyhq.com/accounts/settings/user/api-keys. This is the recommended approach as it works in all contexts (agentic, CI/CD, and interactive). Once both variables are set, re-run npx checkly whoami to verify.
  • Option B: Interactive login — The user runs npx checkly login themselves. This command opens a browser for OAuth authentication and cannot be completed by an AI agent. Tell the user to run the command, complete the browser flow, and let you know when they're done so you can re-run npx checkly whoami to verify.

Step 6: Summarize and test the new monitoring configuration

Read the generated checkly.config.ts (or checkly.config.js) and summarize the configured checks, locations, and frequencies.

Run the following command to test the new monitoring setup:

npx checkly test

If the command passed, congratulate the user and ask them what they want to do next!

Share more Checkly CLI options and ask if they want to deploy their new monitoring setup using npx checkly deploy.