npm package: @pscanf/checkly-cli
Description: Checkly MAC™ CLI
Latest version: 1.0.0

![QA](https://github.com/pscanf/checkly-cli/workflows/QA/badge.svg)

# 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`
1. create a `checks` directory
1. write your first check in json format:
   ```json
   // 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"
         }
       ]
     }
   }
   ```
1. create an API key for your Checkly account @
   https://app.checklyhq.com/account/api-keys
1. create/sync the check on Checkly with the CLI:
   ```sh
   npx checkly sync --apiKey "YOUR_API_KEY"
   ```
1. (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](https://github.com/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](https://github.com/isaacs/node-glob) 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](https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html).
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