# Checkly Monitoring

- Refer to docs for Checkly CLI v6.0.0 and above.
- Check the Checkly CLI output to figure out into which folder the setup was generated.
- Use the [Checkly CLI reference documentation](https://www.checklyhq.com/docs/cli/overview/).
- Use the [Checkly construct reference documentation](https://www.checklyhq.com/docs/constructs/overview/).
- Import and / or require any constructs you need in your code, such as `ApiCheck`, `BrowserCheck`, or `PlaywrightCheck` from the `checkly/constructs` package.
- Always ground generated code and CLI commands against the official documentation and examples in this file.
- Use `runtimeId` for Browser Checks and MultiStep Checks. Runtimes are managed Checkly execution environments with fixed Checkly-provided dependencies such as Playwright, browser binaries, and runtime libraries.
- Use `engine` only for Playwright Check Suites. `engine` selects the JavaScript engine version that runs the user's own Playwright project.

## Using the Checkly CLI

- Use `npx checkly` instead of installing the Checkly CLI globally.
- NEVER make up commands that do not exist.
- Use `npx checkly init` to set up Checkly in an existing project.

## Project Structure

- `checkly.config.ts` - Mandatory global project and CLI configuration. We recommend using TypeScript.
- `*.check.ts|js` - TS / JS files that define the checks.
- `*.spec.ts|js` - TS / JS files that contain Playwright code for Browser and MultiStep checks.
- `src/__checks__` - Default directory where all your checks are stored. Use this directory if it already exists, otherwise create a new directory for your checks.
- `package.json` - Standard npm project manifest.

Here is an example directory tree of what that would look like:

```
.
|-- checkly.config.ts
|-- package.json
`-- src
    `-- __checks__
|-- alert-channels.ts
|-- api-check.check.ts
`-- homepage.spec.ts
```

The `checkly.config.ts` at the root of your project defines a range of defaults for all your checks.

**Reference:** https://www.checklyhq.com/docs/constructs/project/

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

export default defineConfig({
  projectName: "Production Monitoring Suite",
  logicalId: "prod-monitoring-2025",
  repoUrl: "https://github.com/acme/monitoring",
  checks: {
    activated: true,
    muted: false,
    runtimeId: "2025.04",
    frequency: Frequency.EVERY_10M,
    locations: ["us-east-1", "eu-west-1", "ap-southeast-1"],
    tags: ["production", "critical"],
    checkMatch: "**/__checks__/*.check.ts",
    ignoreDirectoriesMatch: ["node_modules/**", "dist/**"],
    playwrightConfig: {
      use: {
        baseURL: "https://app.example.com",
      },
    },
    browserChecks: {
      frequency: Frequency.EVERY_30M,
      testMatch: "**/__tests__/*.spec.ts",
    },
  },
  cli: {
    runLocation: "eu-west-1",
    privateRunLocation: "private-dc1",
    retries: 2,
  },
})
```

## Check and Monitor Constructs

Parse and read further reference documentation when tasked with creating or managing any of the following Checkly constructs.

If the Checkly CLI is installed (`npx checkly version`), use `npx checkly skills configure [CONSTRUCT]` to access up-to-date information:

### `npx checkly skills configure agentic-checks`
Agentic Check construct (`AgenticCheck`) for AI-powered prompt-driven monitoring with skill and env var allowlists

### `npx checkly skills configure api-checks`
Api Check construct (`ApiCheck`), assertions, and authentication setup scripts

### `npx checkly skills configure browser-checks`
Browser Check construct (`BrowserCheck`) with Playwright test files

### `npx checkly skills configure playwright-checks`
Playwright Check Suite construct (`PlaywrightCheck`) for multi-browser test suites

### `npx checkly skills configure multistep-checks`
Multistep Check construct (`MultiStepCheck`) for complex user flows

### `npx checkly skills configure tcp-monitors`
TCP Monitor construct (`TcpMonitor`) with assertions

### `npx checkly skills configure url-monitors`
URL Monitor construct (`UrlMonitor`) with assertions

### `npx checkly skills configure dns-monitors`
DNS Monitor construct (`DnsMonitor`) with assertions

### `npx checkly skills configure icmp-monitors`
ICMP Monitor construct (`IcmpMonitor`) with latency and packet loss assertions

### `npx checkly skills configure heartbeat-monitors`
Heartbeat Monitor construct (`HeartbeatMonitor`)

### `npx checkly skills configure check-groups`
CheckGroupV2 construct (`CheckGroupV2`) for organizing checks

### `npx checkly skills configure alert-channels`
Email (`EmailAlertChannel`), Phone (`PhoneCallAlertChannel`), Slack (`SlackAlertChannel`), and Slack App (`SlackAppAlertChannel`) alert channels

### `npx checkly skills configure supporting-constructs`
Status pages (`StatusPage`), dashboards (`Dashboard`), maintenance windows (`MaintenanceWindow`), and private locations (`PrivateLocation`)

### `npx checkly skills configure environment`
Environment variables: built-in vars Checkly injects at runtime (`CHECK_ID`, `CHECK_NAME`, `REGION`, `CHECKLY_*`), user-defined variables and secrets at global/group/check scope, reference syntax (`process.env` vs `{{handlebars}}`), and the `checkly env` CLI for managing global vars.

## Important: Public URL Requirement

All checks (API, Browser, URL monitors) run on **Checkly's cloud infrastructure**, not on the user's local machine. Target URLs must be publicly accessible from the internet.

- `localhost` and private network URLs will **not work** with `npx checkly test` or `npx checkly deploy`
- For local development, suggest: tunneling tools (ngrok, cloudflare tunnel), preview/staging deployments, or CI preview URLs
- Always confirm with the user that their target URLs are publicly reachable before creating checks

## Check Locations and Plan Entitlements

Not all features and locations are available on all plans. **Before configuring checks, run:**

```bash
npx checkly account plan --output json
```

This returns your exact entitlements and available locations. Use only locations where `available` is `true` in the `locations.all` array. If a feature is disabled, the response includes an `upgradeUrl` to share with the user.

Run `npx checkly skills manage plan` for the full reference.

## Testing and Debugging

- Test checks using the `npx checkly test` command. Pass environment variables with the `-e` flag, results are recorded by default (use `--no-record` to skip), and use `--verbose` to see all errors.

## Deploying

- Deploy checks using the `npx checkly deploy` command. Use `--output` to see the created, updated, and deleted resources. Use `--verbose` to also include each resource's name and physical ID (UUID), which is useful for programmatically referencing deployed resources (e.g. `npx checkly checks get <id>`).