Get started with probe for command line

What is probe-cli?

probe-cli is a lightweight command-line interface (CLI) tool designed for efficient API health checks and automated endpoint testing.

To get started, you will define your API endpoints in a YAML configuration file. probe-cli will then execute requests to these endpoints, validate their responses against your expectations, and report on their status.

Installation

You can install probe-cli globally on your system using npm (Node Package Manager). This allows you to run the probe command directly from any directory in your terminal.

Standard Installation

If you have the necessary permissions (e.g., if you've configured npm without sudo, or on Windows), use:

npm install -g probe-cli

Installation with Sudo (macOS/Linux)

If you encounter EACCES permission errors (like 'permission denied' when installing globally to system directories like /usr/local/lib/node_modules), you may need to use sudo:

sudo npm install -g probe-cli

This temporarily grants administrative privileges to perform the installation.

What does the `-g` flag do?

The -g flag stands for 'global'. When you install an npm package globally, npm places it in a system-wide directory (e.g., /usr/local/bin on macOS/Linux, or a specific directory in your AppData on Windows). This allows you to run the package's executable command (in this case, probe) directly from any location in your terminal, without needing to be inside the project folder where it was originally developed.

Usage

Once installed, you can use the probe command with various options:

probe run: Runs all API tests defined in the default config.yml file in your current directory.
```
$ probe run
```
probe run -c <file> or probe run --config <file>: Runs all tests using a specified configuration file. Replace <file> with the path to your YAML config.
```
$ probe run -c my-custom-config.yml
```
probe run --api "<name>": Runs only a specific API test by its exact name, as defined in your config.yml. Remember to use quotes for names with spaces.
```
$ probe run --api "GitHub API Status"
```
probe init: Creates a sample config.yml file in your current directory to help you get started.
```
$ probe init
```
probe --help or probe -h: Displays the help documentation for the probe-cli tool.

Configuration File (`config.yml`)

The probe-cli tool relies on a YAML configuration file to define the API endpoints you wish to monitor. By default, it looks for a file named config.yml in the directory where you run the command.

You can easily generate a sample config.yml using the probe init command, which provides a good starting point.

Example `config.yml` structure:

# config.yml - Configuration file for API monitoring and testing
apis:
  - name: GitHub API Status
    url: https://www.githubstatus.com/api/v2/status.json
    method: GET
    expectedStatus: 200
    timeout: 5000

  - name: Another Example API
    url: https://api.example.com/health
    method: GET
    expectedStatus: 200
    timeout: 5000

  - name: API with POST request
    url: https://api.example.com/login
    method: POST
    expectedStatus: 200
    timeout: 8000
    # You could add a 'body' field here for POST requests if needed
    # body:
    #   username: testuser
    #   password: testpassword

Each API entry must include at least name, url, and expectedStatus. method defaults to GET and timeout defaults to 10000ms if not specified.