@pscanf/checkly-cli v1.0.0

checkly-cli

Command line utility to create Checkly checks and keep them in sync.

Quickstart

1. install the CLI with npm install @pscanf/checkly-cli
2. create a checks directory
3. write your first check in json format:

   // checks/my-first-check.check.json
   {
     "id": "my-first-check",
     "name": "My First Check",
     "checkType": "API",
     "activated": true,
     "request": {
       "method": "GET",
       "url": "https://api.checklyhq.com/",
       "assertions": [
         {
           "source": "STATUS_CODE",
           "target": "200",
           "property": "",
           "comparison": "EQUALS"
         }
       ]
     }
   }

4. create an API key for your Checkly account @ https://app.checklyhq.com/account/api-keys
5. create/sync the check on Checkly with the CLI:

   npx checkly sync --apiKey "YOUR_API_KEY"

6. (optional) change some property of your check (not the id though!), and re-run the sync command to update the check on Checkly

See pscanf/checkly-cli-usage-example for an example project using the CLI to sync checks as a step of a CI pipeline (with Github Actions).

Available commands

• checkly sync: syncs checks to Checkly. Options:

  • --apiKey (required): Checkly account API key
  • --apiUrl: Checkly API url, defaults to https://api.checklyhq.com/
  • --checks: glob pattern selecting check files, defaults to checks/*.check.json

• checkly configure-vscode: configures VSCode autocompletion for check files. Options:

  • --settings: path to the VSCode settings file, defaults to .vscode/settings.json

How it works

For each check file, the CLI:

• parses and validates the check file
• searches through the checks in your Checkly account to figure out if the check already exists
• if it doesn't exist, creates it
• if it exists, determines if it's up-to-date with the check file. If it is, nothing needs to be done. Else, the check on Checkly is updated

To understand which check in your Checkly account corresponds to which check file, the CLI uses the tags property of Checkly checks, adding to it the id specified in the check file.

Project code structure

This project is organized following the Clean Architecture guidelines. To be honest for such a small project this structure is overkill, but...

General organization

Looking inside the src directory, we have a few subdirectories:

• core: contains the core business logic of the project. We have:

  • in the entities directory, the definitions of the entities the project works with
  • in the usecases directory, the implementation of the use cases (aka functionalities) of the project
  • in the requirements directory, the definitions (interfaces) of the external systems the core needs to operate

• requirementImpls: contains the specific implementations of the requirements interfaces defined in the core

• interfaces: contains implementations of the interfaces through which a user can execute use cases

• mains: contains the entrypoints to run the software

Organization of this project

• core:

  • entities:
    • Check: entity representing a check on Checkly
    • CheckDefinition: entity representing the definition of a check, ie what we put in our check files. Also contains the logic to determine wether a Check and a CheckDefinition are in sync
    • ApiCheckAssertion, CheckType: common data structures
  • usecases:
    • Sync: implements the check-syncing logic
  • requirements:
    • CheckRepository: ~CRUD repository for Check-s

• requirementImpls:

  • ChecklyCheckRepository: implements CheckRepository using the Checkly API

• interfaces:

  • CommandLineInterface: implements the CLI that the user can use to execute usecases. It contains the logic to:
    • gather user input
    • parse and validate it, making sure it conforms to what the usecases expect
    • invoke usecases
    • present output to the user

• mains:

  • cli: entrypoint for the cli