diff --git a/cli/attaching-git-metadata.mdx b/cli/attaching-git-metadata.mdx new file mode 100644 index 00000000..52687f14 --- /dev/null +++ b/cli/attaching-git-metadata.mdx @@ -0,0 +1,38 @@ +--- +title: 'Attaching Git metadata' +sidebarTitle: 'Attaching Git Metadata' +--- + +import CliEnvVars from "/snippets/cli-env-vars.mdx" + +The CLI can attach git metadata like `branch`, `commit sha`, `owner` and more when executing the `test --record` and `deploy` commands. This way you can keep track of +your test sessions and deployed resources in the UI and cross-reference them with any updates to your code. + +For example, in the screenshot below we ran a **test session** from our CI server after the project was deployed to our +Staging environment with the `npx checkly test --record` command. + +![test session with git info](/images/docs/images/cli/test_session_git_data.png) + +After the test succeeds, we **deploy** this check so it runs as a monitor with `npx checkly deploy`. + +![browser check with git info](/images/docs/images/cli/browser_check_git_data.png) + + +## Environment variables + +The CLI will attempt to auto-detect and parse git specific information from your local machine or CI environment, but you +can also set these data items specifically by using environment variables. + + + +For example, if you want to specifically set the Environment you invoke: + +```bash Terminal +CHECKLY_TEST_ENVIRONMENT=Production npx checkly test --record +``` + +Or, if you want to set repo URL you invoke: + +```bash Terminal +CHECKLY_REPO_URL="https://my.git.solution/project/" npx checkly test --record +``` \ No newline at end of file diff --git a/cli/authentication.mdx b/cli/authentication.mdx index 28e07190..c8a0d16a 100644 --- a/cli/authentication.mdx +++ b/cli/authentication.mdx @@ -3,52 +3,52 @@ title: Authentication description: 'How to authenticate with the Checkly CLI' sidebarTitle: 'Authentication' --- -Before you can use the Checkly CLI, you need to authenticate with your Checkly account. +Before you can use the Checkly CLI, you need to authenticate with your Checkly account. There are different ways to authenticate depending on the environment where you are running the CLI from. -## Login +## Interactive -The primary way to authenticate is using the interactive login command: +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. ```bash Terminal npx checkly login ``` -This command will: -- Open your default browser to the Checkly authentication page -- Prompt you to log in to your Checkly account -- Generate an API key that the CLI will use for authentication -- Store the credentials securely on your local machine +Once authenticated, you can switch between accounts using: -## Log Out +```bash Terminal +npx checkly switch +``` -To log out and clear your stored credentials: +... or quickly find out which account you are currently targeting with: ```bash Terminal -npx checkly logout +npx checkly whoami ``` -This will remove the stored API key from your local machine. +To log out and clear your stored credentials: -## Other Authentication Options +```bash Terminal +npx checkly logout +``` -### Environment Variables +## From CI -You can also authenticate using environment variables, which is useful for CI/CD pipelines and automated environments: +You can also authenticate using environment variables, which is useful for CI/CD pipelines and automated environments. -To get your API key: +You will need to export two environment variables in the shell: +- `CHECKLY_API_KEY` +- `CHECKLY_ACCOUNT_ID` -1. Log in to your Checkly dashboard -2. Navigate to **Account Settings** → **API Keys** -3. Create a new API key -4. Use the key in your environment variables or CLI configuration +To get your API key, go to your Settings page in Checkly and grab a API key from [the API keys tab](https://app.checklyhq.com/settings/user/api-keys) and your Account ID from the [Account settings tab](https://app.checklyhq.com/settings/account/general). -Set the account id and API key as follows: +Set the account ID and API key as follows: ```bash Terminal # Set your Checkly API key export CHECKLY_API_KEY=your_api_key_here -# Set your Checkly account ID (optional, CLI will detect automatically) +# Set your Checkly account ID export CHECKLY_ACCOUNT_ID=your_account_id_here ``` @@ -60,36 +60,16 @@ npx checkly whoami This will display your account information and confirm your authentication status. -## Multiple Accounts - -If you work with multiple Checkly accounts, you can switch between them: - -```bash Terminal -# Switch to a different account using interactive prompt -npx checkly switch - -# Switch to a different account using the account id -npx checkly switch --account-id your_account_id - -# View current account -npx checkly whoami -``` - -## Security Best Practices - -- **Never commit API keys** to version control -- **Use environment variables** in production environments -- **Rotate API keys** regularly for security - ## Troubleshooting -### Common Issues + + +If `npx checkly login` doesn't automatically open a browser window to authenticate, you can generate a direct link instead. + +When prompted with: -**"Authentication failed" error:** -- Verify your API key is correct -- Check that your account ID is correct (if specified) -- Ensure your API key hasn't expired +> Do you want to open a browser window to continue with login? (Y/n) -**"Browser didn't open" error:** -- Decline to open the browser automatically and navigate to the authentication URL shown in the terminal -- Copy and paste the URL into your browser +Enter "n". The CLI will provide a link that you can copy and paste into your browser to authenticate. + + \ No newline at end of file diff --git a/cli/basic-workflow.mdx b/cli/basic-workflow.mdx deleted file mode 100644 index 8cfdf55b..00000000 --- a/cli/basic-workflow.mdx +++ /dev/null @@ -1,132 +0,0 @@ ---- -title: Basic Workflow -description: 'Complete workflow for using the Checkly CLI - from testing to deployment' -sidebarTitle: 'Basic Workflow' ---- - -Before using the CLI, you'll need to [authenticate with your Checkly account](/cli/authentication). - -The Checkly CLI follows a simple workflow that enables you to test and deploy your monitoring checks. First run `npx checkly test` to test your checks locally, then run `npx checkly deploy` to deploy them to Checkly's infrastructure. - -## Step 1: Testing Checks Locally - -The `test` command allows you to run your checks locally before deploying them to Checkly's infrastructure. - -### Basic Testing - -```bash Terminal -npx checkly test -``` - -This command will: -- Execute all checks defined in your project -- Run them in your local environment -- Display real-time results and logs -- Show pass/fail status for each check - -### Testing Specific Checks - -You can test individual checks or groups: - - -```bash Test by Check Name -# Match parts of the check name via regular expression -# This will run checks names "Home page check suite" or "API check suite" -npx checkly test --grep=".*check suite" -``` - -```bash Test by File Name -# Specify the entire file name -npx checkly test api.check.ts - -# Match parts of the file name -# This will run api.check.ts and home.check.ts -npx checkly test api home -``` - -```bash Test by Tags -# Specify a single tag -npx checkly test --tags api - -# Specify multiple tags -# This will run checks tagged with "api" and "multistep" -npx checkly test --tags "api,multistep" - -# Specify multiple tag groups -# This will run checks tagged with "api" and "multistep" or "browser" -npx checkly test --tags "api,multistep" --tags "browser" -``` - - -### Testing Options - - -```bash Test in Location -npx checkly test --location "us-east-1" -``` - -```bash Verbose Output -npx checkly test --verbose -``` - -```bash Generate Report -npx checkly test --reporter json -``` - - -### Local Testing Benefits - -- **Fast Feedback**: Get immediate results without waiting for scheduled runs -- **Development Friendly**: Perfect for debugging and development workflows -- **CI/CD Integration**: Can be used in automated testing pipelines to verify preview deployments - -## Step 2: Deploying to Checkly - -Once you've tested your checks locally and are satisfied with the results, deploy them to Checkly's global infrastructure to run as scheduled checks. - -### Basic Deployment - -```bash Terminal -npx checkly deploy -``` - -This command will: -- Parse and validate your Checkly configurations -- Create or update checks in your Checkly account -- Set up the monitoring schedule based on your configuration -- Deploy to all specified locations - -### Deployment Options - - -```bash Preview Changes -npx checkly deploy --preview -``` - -```bash Display Changes after -npx checkly deploy --output -``` - -```bash Force Deployment -npx checkly deploy --force -``` - - -### Deployment Process - -The deployment process includes: - -1. **Validation**: CLI validates your check configurations -2. **Creation/Update**: Checks are created or updated in your account -3. **Scheduling**: Monitoring schedules are configured -4. **Activation**: Checks become active and start monitoring - -## Workflow Best Practices - -1. **Start Local**: Always test changes locally first -2. **Incremental Testing**: Test individual checks during development -3. **Version Control**: Commit your check configurations to Git -4. **Review Changes**: Use `--preview` to review before deployment -5. **Monitor Results**: Check results after deployment - -This comprehensive workflow ensures you can develop, test, and deploy monitoring checks with confidence, maintaining the reliability and performance of your applications. diff --git a/cli/checkly-deploy.mdx b/cli/checkly-deploy.mdx index 0c5f8324..eae5de32 100644 --- a/cli/checkly-deploy.mdx +++ b/cli/checkly-deploy.mdx @@ -5,6 +5,7 @@ sidebarTitle: 'checkly deploy' --- import CliCommandPrerequisites from '/snippets/cli-command-prerequisites.mdx'; +import CliEnvVars from "/snippets/cli-env-vars.mdx" The `checkly deploy` command deploys all your checks and associated resources like alert channels to your Checkly account. This command synchronizes your local monitoring-as-code configuration with your Checkly account. @@ -175,14 +176,7 @@ When you deploy a project, you can attach Git-specific information so changes to The Checkly CLI evaluates Git information from your local or CI environment on a best effort basis. Override any automatically detected values by setting the corresponding environment variables. -| item | auto | variable | description | -|--------------------|-------|--------------------------------------------------------|---------------------------------------------| -| **Repository** | false | `repoUrl` in `checkly.config.ts` or `CHECKLY_REPO_URL` | The URL of your repo on GitHub, GitLab etc. | -| **Commit hash** | true | `CHECKLY_REPO_SHA` | The SHA of the commit. | -| **Branch** | true | `CHECKLY_REPO_BRANCH` | The branch name. | -| **Commit owner** | true | `CHECKLY_REPO_COMMIT_OWNER` | The committer's name or email. | -| **Commit message** | true | `CHECKLY_REPO_COMMIT_MESSAGE` | The commit message. | -| **Environment** | false | `CHECKLY_TEST_ENVIRONMENT` | The environment name, e.g. "staging". | + ## Related Commands diff --git a/cli/cli-vs-terraform-pulumi.mdx b/cli/cli-vs-terraform-pulumi.mdx new file mode 100644 index 00000000..1cccb7d7 --- /dev/null +++ b/cli/cli-vs-terraform-pulumi.mdx @@ -0,0 +1,55 @@ +--- +title: CLI vs. Terraform & Pulumi +description: 'Comparing your options for Monitoring as Code' +sidebarTitle: 'CLI vs Terraform & Pulumi' +--- + +Creating, debugging and managing E2E and synthetic monitoring at scale is best done "as code". Currently, Checkly supports +three tools you can use for your **monitoring as code** (MaC) workflow: + +1. The Checkly CLI. +2. Terraform (through our [Terraform provider](/integrations/iac/terraform/overview/)) +3. Pulumi (through our [Pulumi provider](/integrations/iac/pulumi/overview/)) + +In most cases, the choice depends on what your goals are and how your organization is set up. + +We believe the **Checkly CLI delivers the best-of-breed workflow**. However, there are always trade-offs. Let's list some +pros and cons based on our own experience and user feedback. + +## Terraform vs. Checkly CLI + +If you are a Terraform shop, you can use Checkly to its full capacity. The Checkly CLI adds core capabilities like TS/JS coding, simple Git integration and test execution. + +**Pros** + +`+` Terraform integrates very well with Checkly. We have a well maintained Terraform provider. + +`+` Terraform is comfortable for many Devops engineers used to writing HCL scripts. + +`+` Checkly can be configured almost completely through Terraform resources. + +**Cons** + +`-` Terraform does not allow you to test checks or use TS/JS programming. + +`-` Terraform and its HCL syntax is hard to learn for many app developers. + +`-` Using Terraform with Git is non-trivial. + +## Pulumi vs. Checkly CLI + +**Pros** + +`+` Pulumi integrates well with Checkly. We have a maintained Pulumi provider. + +`+` Pulumi is comfortable with app developers across many languages. + +`+` Checkly can be configured almost completely through Pulumi resources. + +**Cons** + +`-` Pulumi does not really work without signing up for a Pulumi account. + +`-` Pulumi does not allow you to run and debug checks from your local dev environment. + +`-` Pulumi is not optimized for testing and monitoring use cases. diff --git a/platform/runtimes/dependencies.mdx b/cli/dependencies.mdx similarity index 66% rename from platform/runtimes/dependencies.mdx rename to cli/dependencies.mdx index 2f1d8845..d6ccc04e 100644 --- a/platform/runtimes/dependencies.mdx +++ b/cli/dependencies.mdx @@ -1,18 +1,17 @@ --- -title: Using npm packages and local dependencies +title: Using NPM packages and local dependencies sidebarTitle: NPM & Local Dependencies - --- -Checkly lets you use JavaScript / TypeScript in your Browser and Multistep checks, and in API check setup & teardown scripts. -Checks are able to use NPM packages that are defined in [our runtimes](/platform/runtimes/overview), as well as import local JavaScript and TypeScript files. - +Checkly lets you use JavaScript / TypeScript in your [Browser](/detect/synthetic-monitoring/browser-checks/overview) and [Multistep](/detect/synthetic-monitoring/multistep-checks/overview) checks, [API check setup & teardown scripts](/detect/synthetic-monitoring/api-checks/set-up-and-tear-down), and [Playwright Check Suites](/detect/synthetic-monitoring/playwright-checks/overview). Checks are able to use NPM packages, as well as import local JavaScript and TypeScript files. ## NPM packages +### Browser, Multistep, and API Checks + Not all NPM packages from NPM are available inside the context of a Check. -The JavaScript code for checks executes in a runtime environment managed by Checkly. +The JavaScript code for these check types executes in a runtime environment managed by Checkly. Runtime versions can be selected by setting a `runtimeId`. This can be configured at the check and group level using constructs, and a default value for the project can be set in the [project configuration file](/constructs/project#param-checks-runtime-id). @@ -28,6 +27,11 @@ A runtime contains among others: - [Browse the latest runtime specs](/platform/runtimes/runtime-specification) - [Learn more about runtimes](/platform/runtimes/overview) +- [Why can't I import any NPM package or other 3rd party dependencies?](/platform/runtimes/overview#why-can’t-i-import-any-npm-package-or-other-3rd-party-dependencies%3F) + +### Playwright Check Suites + +Playwright Check Suites don't use our predefined runtimes. Instead, you can install [custom dependencies](/detect/synthetic-monitoring/playwright-checks/custom-dependencies/), including private packages or packages from a custom registry. ## Local Dependencies @@ -60,7 +64,7 @@ export async function gitHubLogin (page, username, password) { In `login.spec.ts` we define the actual Playwright test. This file can import the `gitHubLogin` function from `login-helper.ts`. -It also reads the username and password from [remote environment variables](/cli/environment-variables). +It also reads the username and password from [remote environment variables](/cli/environment-variables#remote-environment-variables). ```ts login.spec.ts // @ts-ignore @@ -75,7 +79,7 @@ test('Github login', async ({ page }) => { }) ``` -`login.check.ts` initializes a new [BrowserCheck construct](/cli/constructs-reference/#browsercheck). Note that it's only necessary to configure the main Playwright file `login.spec.ts`. The `login-helper.ts` dependency is automatically detected by the CLI. +`login.check.ts` initializes a new [BrowserCheck construct](/constructs/browser-check). Note that it's only necessary to configure the main Playwright file `login.spec.ts`. The `login-helper.ts` dependency is automatically detected by the CLI. ```ts login.check.ts import { BrowserCheck } from 'checkly/constructs' @@ -92,7 +96,3 @@ After running [`npx checkly deploy`](/cli/checkly-deploy), you can see in the We ![login check with helper file in dependencies](/images/docs/images/cli/local-dependency.png) The maximum total size of a Checkly project when deploying or running a test session, including local dependencies, is 40 MB. - -## Why can't I import any NPM package or other 3rd party dependencies? - -Please see [this paragraph in our runtime docs](/platform/runtimes/overview#why-can’t-i-import-any-npm-package-or-other-3rd-party-dependencies%3F). diff --git a/cli/importing.mdx b/cli/importing.mdx index e87199ef..a320861b 100644 --- a/cli/importing.mdx +++ b/cli/importing.mdx @@ -1,6 +1,6 @@ --- title: 'Importing existing Checks into your CLI project' -description: 'Learn how to import checks from the UI into Checkly' +description: 'Learn how to import checks from the UI into the CLI' sidebarTitle: 'Importing Resources From the UI' --- @@ -82,4 +82,4 @@ If `export` is not used, the CLI code generation will still reference the correc ## Next steps -Once you have a fully CLI managed setup you are ready to leverage Monitoring as Code to improve your setup. Check our how to [dynamically creating monitors](/constructs/including-checks) and how to [integrate Checkly in your CI/CD process](/integrations/ci-cd/overview). +Once you have a fully CLI managed setup you are ready to leverage Monitoring as Code to improve your setup. Learn how to [dynamically create monitors](/constructs/dynamic-monitor-creation), [add git metadata to Checkly](/cli/attaching-git-metadata), and [integrate Checkly in your CI/CD process](/integrations/ci-cd/overview). diff --git a/cli/installation.mdx b/cli/installation.mdx new file mode 100644 index 00000000..e48fdc2f --- /dev/null +++ b/cli/installation.mdx @@ -0,0 +1,132 @@ +--- +title: 'Intallation' +description: 'Creating a CLI project from scratch' +sidebarTitle: 'Installation' +--- + +To kickstart a new project with the CLI, we recommend running `npm create checkly@latest`. But you can also add the CLI +from scratch with the following steps. + +## Prerequisites + +- Node.js `v16.x` or higher. +- A text editor like [Visual Studio Code](https://code.visualstudio.com/). + +## Installation + +First, install the CLI. + +```bash Terminal +npm i --save-dev checkly +``` + +To use TypeScript, also install `ts-node` and `typescript`: + +```bash Terminal +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. + + + + ```ts {title="checkly.config.ts"} + 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', + } + }) + ``` + + + ```js {title="checkly.config.js"} + 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](/cli/authentication) and pick a Checkly account. Make sure you have [signed up for a free account on checklyhq.com](https://www.checklyhq.com/) +before hand or just sign up for a new account straight from the terminal. + +```bash Terminal +npx checkly login +``` + +## Direct download + +If you cannot access the npm registry directly, you can also download the Checkly CLI via our CDN. + +- [MacOS / Darwin](https://cdn.checklyhq.com/downloads/checkly-cli/4.9.0/darwin/checkly-cli.zip) +- [Windows](https://cdn.checklyhq.com/downloads/checkly-cli/4.9.0/windows/checkly-cli.zip) +- [Linux](https://cdn.checklyhq.com/downloads/checkly-cli/4.9.0/linux/checkly-cli.tar.gz) + +The download is a zipped folder containing a full installation of [the boilerplate example project](https://github.com/checkly/checkly-cli/tree/main/examples/boilerplate-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`. + +```bash 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` diff --git a/cli/overview.mdx b/cli/overview.mdx index b83d5b83..64e44118 100644 --- a/cli/overview.mdx +++ b/cli/overview.mdx @@ -4,68 +4,80 @@ description: 'Complete guide to the Checkly CLI for monitoring as code' sidebarTitle: 'Overview' --- -import CliInstallation from '/snippets/cli-installation.mdx'; -import CliProjectInit from '/snippets/cli-project-init.mdx'; +import MainCicdCards from "/snippets/main-cicd-cards.mdx" - -See [the general quickstart guide](quickstarts/browser-check/) if you want to start creating your monitoring in the Checkly app first. - +The Checkly CLI gives you a JavaScript/TypeScript-native workflow for coding, testing and deploying synthetic +monitoring at scale, from your code base. The Checkly CLI comes with **native `@playwright/test` support.** No lock-in, +just write standard `*.spec.ts` files. -The Checkly CLI enables monitoring as code, allowing you to create, test, and deploy synthetic monitoring checks directly from your codebase. Write checks in JavaScript/TypeScript, test them locally, and deploy them to Checkly's global monitoring infrastructure. +## Starting your first project -## Installing +Get started by installing the CLI using the following command which will guide you through the required steps to +set up a fully working example. -**Recommended approach:** Create a new project with the CLI: - - +```bash Terminal +npm create checkly@latest +``` -**Alternative:** Install as a dev dependency in existing projects: +Now, login to your Checkly account or sign up for a new account right from the terminal. - +```bash Terminal +npx checkly login +``` -Recommended: Install [jiti](https://www.npmjs.com/package/jiti) to use TypeScript for your Checkly monitoring setup. +After this, let's dry run the Checks in your new project against the global Checkly infrastructure. ```bash Terminal -npm i --save-dev jiti +npx checkly test ``` -Then, discover all available commands using: +This should report the following output to your terminal -```bash Terminal -npx checkly --help ``` +Running 4 checks in eu-west-1. + +src/__checks__/api.check.ts + ✔ Books API (222ms) +src/__checks__/home.check.ts + ✔ Home page (24s) + ✔ Login Check (5s) +src/__checks__/multi-step-spacex.check.ts + ✔ SpaceX MS (4s) + +4 passed, 4 total +``` + +Lastly, you deploy your Checks and related alert channels to Checkly, so we run your checks around the clock. -## Checking the Version ```bash Terminal -npx checkly --version +npx checkly deploy ``` -## Command Reference +You just created your entire synthetic monitoring setup with API and Playwright-based Browser Checks from your code base! +Open up [your Checkly dashboard](https://app.checklyhq.com) and you should see your check, ready to start monitoring around the clock. -### Authentication & Account Management -- [`checkly login`](/cli/checkly-login) - Authenticate with your account -- [`checkly logout`](/cli/checkly-logout) - Sign out and remove tokens -- [`checkly whoami`](/cli/checkly-whoami) - Display current account info -- [`checkly switch`](/cli/checkly-switch) - Switch between accounts +For a custom installation check out [our installation docs](/cli/installation/). -### Development & Testing -- [`checkly test`](/cli/checkly-test) - Run checks locally for testing -- [`checkly pw-test`](/cli/checkly-pw-test) - Run Playwright checks locally for testing -- [`checkly runtimes`](/cli/checkly-runtimes) - List available runtime environments -- [`checkly sync-playwright`](/cli/checkly-sync-playwright) - Sync Playwright configuration +## Using AI IDEs and Copilots -### Deployment & Management -- [`checkly deploy`](/cli/checkly-deploy) - Deploy checks to your account -- [`checkly destroy`](/cli/checkly-destroy) - Remove all project resources -- [`checkly trigger`](/cli/checkly-trigger) - Run deployed checks on-demand +Checkly is designed to work with AI IDEs and Copilots. You can use your preferred provider to generate code for API +Checks, Browser Checks and all other constructs. -### Environment & Import -- [`checkly env`](/cli/checkly-env) - Manage global environment variables -- [`checkly import`](/cli/checkly-import) - Import existing resources into CLI + + + Download the Checkly instructions file and let copilot generate Checkly CLI code for you. + + + Download the Checkly `.mdc` rules file and let Cursor generate Checkly CLI code for you. + + + Download the Checkly rules file and let Claude generate Checkly CLI code for you. + + +## Integrating with CI/CD -## Next Steps +After kicking the tires, you should delegate the testing and deploying of your checks to your CI/CD pipeline. Check our +docs on [setting up the Checkly CLI with your favourite CI/CD platform](/integrations/ci-cd/overview). -1. **[Authenticate](/cli/authentication)** - Get started with the CLI -2. **[Create your first test](/cli/checkly-test)** - Write and test a check locally -3. **[Deploy your monitoring](/cli/checkly-deploy)** - Push checks to Checkly + \ No newline at end of file diff --git a/constructs/dynamic-monitor-creation.mdx b/constructs/dynamic-monitor-creation.mdx new file mode 100644 index 00000000..f3c771d7 --- /dev/null +++ b/constructs/dynamic-monitor-creation.mdx @@ -0,0 +1,132 @@ +--- +title: 'Dynamic monitor creation' +sidebarTitle: 'Dynamic Monitor Creation' +--- + +The [Checkly CLI](/cli/overview/) enables you to code your entire monitoring setup taking full advantage of the flexibility of TypeScript/JavaScript. Reusing language constructs that you are already familiar with, you will be able to create a MaC setup that neatly fits your unique use cases and workflows. + +This page shows a few examples. + +## Similar checks from a list of targets + +Iterating through lists of target URLs is an easy way to manage checks at scale while avoiding code duplication. + +```ts __checks__/api.check.ts +import { ApiCheck } from 'checkly/constructs' + +const publicResources = ['/public-stats', '/v1/runtimes'] + +for (const publicResource of publicResources) { + new ApiCheck(`public-resource_${publicResource}`, { + name: `Public Resource ${publicResource}`, + request: { + url: `https://api.checkly.com${publicResource}`, + method: 'GET', + followRedirects: true, + skipSsl: false, + assertions: [ AssertionBuilder.statusCode().equals(200) ] + } + }) +} +``` + +Asynchronous operations are supported by exporting an async function from your check files, too. + +```ts __checks__/api.check.ts +import { ApiCheck } from 'checkly/constructs' +import { getPublicResources } from './helpers' + +// an exported async function to signal that +// this check file performs asynchronous operations +export default async function createApiChecks() { + const publicResources = await getPublicResources(); + + for (const publicResource of publicResources) { + new ApiCheck(`public-resource_${publicResource}`, { + name: `Public Resource ${publicResource}`, + request: { + url: `https://api.checkly.com${publicResource}`, + method: 'GET', + followRedirects: true, + skipSsl: false, + assertions: [ AssertionBuilder.statusCode().equals(200) ] + } + }) + } +} +``` + +## Separate groups for prod and pre-prod + +Iterating through target environments (like `preview` and `production`) linked to [`Group`](/constructs/check-group-v2) resources allows you to reuse existing `Check` definitions. + +```ts __checks__/browser.check.ts +import fs from 'fs' +import { BrowserCheck } from 'checkly/constructs' +import { groupProd, groupPreview } from './groups.check' + +// This reads a directory and extracts all file paths containing '.spec.ts' +const files = fs.readdirSync('__checks__/') +const specFiles = files.filter((filename) => { + return filename.includes('.spec.ts') +}) + +// This is the list of environments and their matching group; it can be extended easily +const environments = [ + { name: 'preview', group: groupPreview }, + { name: 'production', group: groupProd }, +] + +// Here we create a new browser check for each environment x testspec combination +// Checks are added to the right groups - the group will set the right env variable for the target URL +environments.forEach((environment) => { + for (const specFile of specFiles) { + new BrowserCheck(`${specFile}${environment.name}`, { + name: `${specFile} [${environment.name}]`, + tags: [`${environment.name}`], + group: environment.group, + code: { + entrypoint: specFile, + }, + }) + } +}) +``` + +You can handle potential differences between target environments via group-level [environment variables](/platform/variables/), which are made available to all checks within a group. + +```ts __checks__/group.check.ts +import { CheckGroupV2 } from 'checkly/constructs' +import { smsChannel, emailChannel } from '../alert-channels' +const alertChannels = [smsChannel, emailChannel] + +export const groupPreview = new CheckGroupV2('group-browser-preview', { + name: 'WebShop - Preview', + activated: true, + muted: false, + runtimeId: '2025.04', + locations: ['us-east-1', 'eu-west-1'], + tags: ['mac', 'preview'], + // You can use group-level environment vars to point each group's checks to the right target URL + environmentVariables: [ { key: 'TARGET_URL', value: 'https://preview.mywebsite.com' }], + apiCheckDefaults: {}, + concurrency: 100, + alertEscalationPolicy: 'global', + alertChannels +}) + +export const groupProd = new CheckGroupV2('group-browser-prod', { + name: 'WebShop - Production', + activated: true, + muted: false, + runtimeId: '2025.04', + locations: ['us-east-1', 'eu-west-1'], + tags: ['mac', 'production'], + // You can use group-level environment vars to point each group's checks to the right target URL + environmentVariables: [ { key: 'TARGET_URL', value: 'https://www.mywebsite.com' }], + apiCheckDefaults: {}, + concurrency: 100, + alertEscalationPolicy: 'global', + alertChannels +}) +``` \ No newline at end of file diff --git a/constructs/overview.mdx b/constructs/overview.mdx index 602fff10..b52c22f8 100644 --- a/constructs/overview.mdx +++ b/constructs/overview.mdx @@ -7,6 +7,11 @@ sidebarTitle: 'Overview' import JsTsNote from '/snippets/js-ts-note.mdx'; import ChecklyConfigCodeBlock from '/snippets/checkly-config-example-code-block.mdx'; + +Every resource you create using the [Checkly CLI](/cli/overview/) is represented by a "construct": it's a class you import from `checkly/constructs`, +for instance an `ApiCheck` or `EmailAlertChannel`. A construct is the "as-code" representation of the eventual resource +created / deleted / updated on the Checkly cloud once you run `npx checkly deploy`. + You must install the [Checkly CLI](/cli/overview) before you can use constructs. @@ -16,13 +21,13 @@ Constructs are JavaScript/TypeScript classes that represent your all monitoring ```ts api.check.ts -import { ApiCheck, AssertionBuilder } from "checkly/constructs" +import { ApiCheck, AssertionBuilder } from 'checkly/constructs' -new ApiCheck("api-health-check", { - name: "API Health Check", +new ApiCheck('api-health-check', { + name: 'API Health Check', request: { - url: "https://danube-web.shop/api/books", - method: "GET", + url: 'https://danube-web.shop/api/books', + method: 'GET', assertions: [ AssertionBuilder.statusCode().equals(200), ], @@ -31,13 +36,13 @@ new ApiCheck("api-health-check", { ``` ```js api.check.js -const { ApiCheck, AssertionBuilder } = require("checkly/constructs") +const { ApiCheck, AssertionBuilder } = require('checkly/constructs') -new ApiCheck("api-health-check", { - name: "API Health Check", +new ApiCheck('api-health-check', { + name: 'API Health Check', request: { - url: "https://danube-web.shop/api/books", - method: "GET", + url: 'https://danube-web.shop/api/books', + method: 'GET', assertions: [ AssertionBuilder.statusCode().equals(200), ], @@ -52,7 +57,9 @@ Test this API check with `npx checkly test` and transform it to production monit ## Project Structure -Configure your Checkly project by creating and editing the `checkly.config.ts`. The configuration file enables you to set default settings like monitoring locations, configure alert settings and organize your Checkly files to match your project requirements. +- `checkly.config.ts` - Mandatory global project and CLI configuration. We recommend using TypeScript. +- `src/__checks__/*` - TS/JS files defining your checks and other resources. +- `package.json` - Standard NPM project manifest. Here is an example directory tree of what that would look like: @@ -68,107 +75,88 @@ Here is an example directory tree of what that would look like: ``` -We recommend separating your monitoring resources from your application code using the `__checks__` path convention. However, it's up to you to define where your monitoring setup will be configured. +The `checkly.config.ts` at the root of your project defines a range of defaults for all your checks. ## Project Configuration As your project grows, you will want to override these defaults for specific checks or check groups. The recommended way to tackle this is using a mix of **global** and **local** configuration. - - - Your global `checkly.config` holds a set of defaults for your project. +### Global Configuration +As mentioned, your global `checkly.config.ts` holds a set of defaults for your project, checks, and some CLI commands. Use `defineConfig` to configure your Checkly project. - + - Find a full reference of all project properties in [the `Project` configuration section](/constructs/project). - +Find a full reference of all project properties in [the `Project` construct section](/constructs/project). - - Override any of the `checkly.config` settings at the individual check level. +### Local Configuration +Override any of the `checks` global configuration settings at the individual check level. - + ```ts __checks__/api.check.ts -import { ApiCheck, AssertionBuilder, Frequency } from "checkly/constructs" +import { ApiCheck, AssertionBuilder, Frequency } from 'checkly/constructs' -new ApiCheck("books-api", { - name: "Books API", - locations: ["ap-south-1"], // overrides the locations property +new ApiCheck('books-api', { + name: 'Books API', + locations: ['ap-south-1'], // overrides the locations property frequency: Frequency.EVERY_30M, // overrides the frequency property request: { - method: "GET", - url: "https://danube-web.shop/api/books", + method: 'GET', + url: 'https://danube-web.shop/api/books', assertions: [AssertionBuilder.statusCode().equals(200)], }, }) ``` ```js __checks__/api.check.js -const { ApiCheck, AssertionBuilder, Frequency } = require("checkly/constructs") +const { ApiCheck, AssertionBuilder, Frequency } = require('checkly/constructs') -new ApiCheck("books-api", { - name: "Books API", - locations: ["ap-south-1"], // overrides the locations property +new ApiCheck('books-api', { + name: 'Books API', + locations: ['ap-south-1'], // overrides the locations property frequency: Frequency.EVERY_30M, // overrides the frequency property request: { - method: "GET", - url: "https://danube-web.shop/api/books", + method: 'GET', + url: 'https://danube-web.shop/api/books', assertions: [AssertionBuilder.statusCode().equals(200)], }, }) ``` - + - Find a full reference of all check properties in [the `ApiCheck` construct](/cli/constructs-reference/#apicheck) or [`BrowserCheck` construct section](/cli/constructs-reference/#browsercheck). - - +Find a full reference of all check properties in [the `ApiCheck` construct](/constructs/api-check) or [`BrowserCheck` construct section](/constructs/browser-check). ## Logical IDs -Every construct requires a unique `logicalId` as its first parameter. This ID tracks resources across deployments and updates. - -**Key rules:** -- IDs must be unique within your project -- Changing an ID creates a new resource and removes the old one -- IDs can be any string up to 255 characters - -```ts api-check.ts -// Good: descriptive, unique IDs -new ApiCheck('homepage-api-check', { /* ... */ }) -new ApiCheck('user-auth-check', { /* ... */ }) +Assigning a `logicalId` is crucial when creating a construct. Remember the following rules when creating and updating constructs: -// Bad: duplicate IDs will cause errors -new ApiCheck('check-1', { /* ... */ }) -new ApiCheck('check-1', { /* ... */ }) // ❌ Duplicate ID +1. Every construct needs to have a `logicalId`. This is the first argument when instantiating a class, i.e. +```ts +const check = new ApiCheck('my-logical-id', { name: 'My API check' }) ``` -## Programming with Constructs +2. Every `logicalId` needs to be unique within the scope of a `Project`. +3. A `Project` also has a `logicalId`. This needs to be unique within the scope of the Checkly account. +4. A `logicalId` can be any string up to 255 characters in length. +5. There is no hard limit on the amount of `Project`s you can have in your Checkly account. -Constructs are JavaScript/TypeScript classes that you can initialize programmatically. Use standard programming patterns: +Behind the scenes, we use the `logicalId` to create a graph of your resources so we know what to persist, update and remove +from our database. Changing the `logicalId` on an existing resource in your code base will tell the Checkly backend that +a resource was removed and a new resource was created. -```ts api-check.ts -// Share alert channels across checks -const alertChannel = new EmailAlertChannel("team-alerts", { - address: "team@example.com", -}) +When using the Checkly CLI to manage multiple projects and repositories, each project's `logicalId` should be unique within the Checkly account. +The project's `logicalId` is used during the Checkly CLI commands to detect exactly which project is being used. +If multiple projects are using the same project `logicalId`, deploying one project will delete the checks that were deployed by another project. +The project `logicalId` can be configured in the project's [global configuration](/constructs/project). -// Define your endpoints -const endpoints = ["/api/books", "/api/books/22"] - -// Create a new check for each endpoint -endpoints.forEach( - (endpoint) => - new ApiCheck(`${endpoint.replace("/", "-")}-check`, { - name: `${endpoint} Check`, - request: { - method: "GET", - url: `https://danube-web.shop/${endpoint}`, - }, - alertChannels: [alertChannel], - }) -) -``` + +When changing the logical ID of a project you will keep all resources on your Checkly account, unless you run [`npx checkly destroy`](/cli/checkly-destroy/) to remove the old project. + + +## Programming with Constructs -## Next Steps +All resources you can create and manage using the Checkly CLI are derived from "constructs". These constructs are just +[TypeScript classes](https://github.com/checkly/checkly-cli/tree/main/packages/cli/src/constructs). -Each construct has detailed documentation with examples, configuration options, and best practices. Start with the construct type you need, and start configuring your monitoring infrastructure in code. +You can use standard JS/TS programming to use these constructs to create the monitoring setup of your +choice. Loops, variables, if-statements, file imports, extensions etc. [Here are some examples.](/constructs/dynamic-monitor-creation) \ No newline at end of file diff --git a/detect/synthetic-monitoring/browser-checks/snippets.mdx b/detect/synthetic-monitoring/browser-checks/snippets.mdx index 6009d831..d2eeb60d 100644 --- a/detect/synthetic-monitoring/browser-checks/snippets.mdx +++ b/detect/synthetic-monitoring/browser-checks/snippets.mdx @@ -12,7 +12,7 @@ Snippets can be useful for: - a common setup or teardown procedure -If you are using [the Checkly CLI](/cli/overview), you don't need to use snippets. Use `import` or `require` to add any local dependencies from your repo. Check the docs on [using local dependencies](/platform/runtimes/dependencies#local-dependencies) to learn more. +If you are using [the Checkly CLI](/cli/overview), you don't need to use snippets. Use `import` or `require` to add any local dependencies from your repo. Check the docs on [using local dependencies](/cli/dependencies#local-dependencies) to learn more. ## How to use snippets diff --git a/docs.json b/docs.json index fcdb9b89..310beaf7 100644 --- a/docs.json +++ b/docs.json @@ -110,8 +110,7 @@ "group": "Runtimes", "pages": [ "platform/runtimes/overview", - "platform/runtimes/runtime-specification", - "platform/runtimes/dependencies" + "platform/runtimes/runtime-specification" ] }, "platform/allowlisting-traffic", @@ -355,7 +354,8 @@ "integrations/ai/overview", "integrations/ai/claude", "integrations/ai/cursor", - "integrations/ai/copilot" + "integrations/ai/copilot", + "integrations/ai/windsurf" ] }, { @@ -464,8 +464,15 @@ "pages": [ "constructs/overview", - "constructs/including-checks" - + { + "group": "Quickstarts", + "pages": [ + "constructs/quickstarts/browser-check", + "constructs/quickstarts/playwright-check" + ] + }, + "constructs/including-checks", + "constructs/dynamic-monitor-creation" ] }, @@ -543,10 +550,13 @@ "group": "Getting Started", "pages": [ "cli/overview", + "cli/installation", "cli/authentication", - "cli/basic-workflow", "cli/environment-variables", - "cli/importing" + "cli/dependencies", + "cli/attaching-git-metadata", + "cli/importing", + "cli/cli-vs-terraform-pulumi" ] }, { diff --git a/images/claude-icon.svg b/images/claude-icon.svg new file mode 100644 index 00000000..4b70dc9f --- /dev/null +++ b/images/claude-icon.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/integrations/ai/windsurf.mdx b/integrations/ai/windsurf.mdx new file mode 100644 index 00000000..26561826 --- /dev/null +++ b/integrations/ai/windsurf.mdx @@ -0,0 +1,22 @@ +--- +title: 'Windsurf' +description: 'Learn how to use Windsurf to create checks.' +sidebarTitle: 'Windsurf' +--- + + + + ```bash Terminal + mkdir -p .windsurf/rules && curl -o .windsurf/rules/checkly.md "https://www.checklyhq.com/docs/ai/checkly.rules.md" -L + ``` + + + ```bash Terminal + New-Item -ItemType Directory -Path ".windsurf\rules" -Force + Invoke-WebRequest -Uri "https://www.checklyhq.com/docs/ai/checkly.rules.md" -OutFile ".windsurf\rules\checkly.md" + ``` + + + +You can now reference the `checkly.md` using `@checkly.md` file in your WindSurf chats and ask it to generate code for +API Checks, Browser checks, Multistep checks and all other constructs. \ No newline at end of file diff --git a/integrations/ci-cd/jenkins/overview.mdx b/integrations/ci-cd/jenkins/overview.mdx index e7a55818..d1b142d7 100644 --- a/integrations/ci-cd/jenkins/overview.mdx +++ b/integrations/ci-cd/jenkins/overview.mdx @@ -2,6 +2,9 @@ title: Integrating Checkly in Jenkins sidebarTitle: Jenkins --- + +import CliEnvVars from "/snippets/cli-env-vars.mdx" + We've optimized the [Checkly CLI](/cli/overview/) to work in any CI/CD workflow. Here are the basics you need to know that will come in handy when adapting the examples we give you to your own, specific setup. 1. For **authentication**, make sure to set the `CHECKLY_API_KEY` and `CHECKLY_ACCOUNT_ID` parameters as environment variables @@ -13,15 +16,7 @@ in your CI/CD platform. When using the `--record` flag, the CLI will attempt to parse `git` specific information from the environment to display in the recorded test session as metadata. However, you can also set these data items specifically by using environment variables. -| item | auto | variable | description | -|--------------------|--------------|--------------------------------------------------------|--------------------------------------------| -| **Repository** | false | `repoUrl` in `checkly.config.ts` or `CHECKLY_REPO_URL` | The URL of your repo on GitHub, GitLab etc. | -| **Commit hash** | true | `CHECKLY_REPO_SHA` | The SHA of the commit. | -| **Branch** | true | `CHECKLY_REPO_BRANCH` | The branch name. | -| **Commit owner** | true | `CHECKLY_REPO_COMMIT_OWNER` | The committer's name or email. | -| **Commit message** | true | `CHECKLY_REPO_COMMIT_MESSAGE` | The commit message. | -| **Environment** | false | `CHECKLY_TEST_ENVIRONMENT` | The environment name, e.g. "staging" | - + ## A Basic pipeline example diff --git a/integrations/ci-cd/overview.mdx b/integrations/ci-cd/overview.mdx index 4d24a8a6..d3db2207 100644 --- a/integrations/ci-cd/overview.mdx +++ b/integrations/ci-cd/overview.mdx @@ -4,7 +4,8 @@ description: 'Core to our Monitoring as Code approach is running your checks fro sidebarTitle: 'Overview' --- - +import MainCicdCards from "/snippets/main-cicd-cards.mdx" +import CliEnvVars from "/snippets/cli-env-vars.mdx" Regardless of the provider or platform you use, integrating Checkly into your CI/CD pipeline boils down to **four basic steps**: @@ -19,29 +20,7 @@ Simultaneously , you can life cycle (create/update/delete) your checks from your The preferred and most flexible way to integrate Checkly with your CI/CD is through the [Checkly CLI](/cli). - - - Run the Checkly CLI from GitHub Actions, export summary reports and integrate with mono repos - - - Run the Checkly CLI from GitLab CI pipelines, using separate e2e-test and deploy jobs. - - - Run the Checkly CLI from a Jenkins pipeline using a Jenkinsfile. - - + ## CI/CD Integration using vendor webhooks @@ -62,13 +41,4 @@ When using the `--record` flag, the CLI will attempt to parse `git` specific inf the environment to display in the recorded test session as metadata. However, you can also set these data items specifically by using environment variables. - -| item | auto | variable | description | -|--------------------|--------------|--------------------------------------------------------|--------------------------------------------| -| **Repository** | false | `repoUrl` in `checkly.config.ts` or `CHECKLY_REPO_URL` | The URL of your repo on GitHub, GitLab etc. | -| **Commit hash** | true | `CHECKLY_REPO_SHA` | The SHA of the commit. | -| **Branch** | true | `CHECKLY_REPO_BRANCH` | The branch name. | -| **Commit owner** | true | `CHECKLY_REPO_COMMIT_OWNER` | The committer's name or email. | -| **Commit message** | true | `CHECKLY_REPO_COMMIT_MESSAGE` | The commit message. | -| **Environment** | false | `CHECKLY_TEST_ENVIRONMENT` | The environment name, e.g. "staging" | - + \ No newline at end of file diff --git a/snippets/cli-env-vars.mdx b/snippets/cli-env-vars.mdx new file mode 100644 index 00000000..20fab5a3 --- /dev/null +++ b/snippets/cli-env-vars.mdx @@ -0,0 +1,8 @@ +| Item | Auto | Variable | Description | +|--------------------|--------------|--------------------------------------------------------|--------------------------------------------| +| **Repository** | false | `repoUrl` in `checkly.config.ts` or `CHECKLY_REPO_URL` | The URL of your repo on GitHub, GitLab etc. | +| **Commit hash** | true | `CHECKLY_REPO_SHA` | The SHA of the commit. | +| **Branch** | true | `CHECKLY_REPO_BRANCH` | The branch name. | +| **Commit owner** | true | `CHECKLY_REPO_COMMIT_OWNER` | The committer's name or email. | +| **Commit message** | true | `CHECKLY_REPO_COMMIT_MESSAGE` | The commit message. | +| **Environment** | false | `CHECKLY_TEST_ENVIRONMENT` | The environment name, e.g. "staging" | \ No newline at end of file diff --git a/snippets/main-cicd-cards.mdx b/snippets/main-cicd-cards.mdx new file mode 100644 index 00000000..7f19831f --- /dev/null +++ b/snippets/main-cicd-cards.mdx @@ -0,0 +1,23 @@ + + + Run the Checkly CLI from GitHub Actions, export summary reports and integrate with mono repos + + + Run the Checkly CLI from GitLab CI pipelines, using separate e2e-test and deploy jobs. + + + Run the Checkly CLI from a Jenkins pipeline using a Jenkinsfile. + +