## Show help

```text
./amcli -h

  IML Appmonitor as CLI client 0.4

This client performs appmonitor checks and puts the results as JSON to stdout.
It contains all checks that are available in the PHP appmonitor client.
You can use the compiled binary to monitor any non PHP webapp without 
implementing the checks for your programming language.

You need to reference an INI file that contains the metadata and all checks.
Have a look to the online documentation for details.
You find example snippets in the source code of this project in tests/config/.

  👤 Author: Axel Hahn
  📄 Source: https://git-repo.iml.unibe.ch/iml-open-source/appmonitor-cli-client
  📜 License: GNU GPL 3.0
  📗 Docs: https://os-docs.iml.unibe.ch/appmonitor-cli-client/

(c) 2025 Institute for Medical Education * University of Bern

...............................................................................


✨ SYNTAX:

    amcli [OPTIONS] --ini=<INI-FILE>


🔷 OPTIONS:

    -h, --help      Print this help and exit
    -i, --ini       Set an INI File to parse
    -l, --list      list available checks and exit
    -m, --modules   list available Php modules in this binary and exit
    -v, --verbose   Enable verbose output (written to STDERR)
    -V, --version   Show version and exit


👉 EXAMPLES:

    amcli -i=my.ini
    amcli --ini=my.ini
        Execute checks from INI file 'my.ini'.

    amcli --list
        List available checks.

```

## Execute checks

Checks can be defined by writing an INI file that contains meta information and sections for each check.
To execute it use the `--ini` parameter and reference the file (as absolute path or relative to your current working directory).

`[<PATH>]amcli --ini=<FILENAME>`

## Define checks

The infomation for the checks is structured in sections.

* `[meta]` - defines the meta information for the web application, its hostname and more. This section is optional but I am naerly sure you want to override the defaults
* `[notifications]` - define application specific receivers that get a message from appmonitor server on status change of this app.
* `[<OTHER>]` - define one check per section.

First an example:

```ini
[meta]
host = "www.example.com"
website = "Company website"
ttl = 300
tags[]="monitoring"

[notifications]
email[]="support@example.com"
email[]="webmaster@example.com"

slack["#support-channel"]="https://hooks.slack.com/services/XXXXXX/YYYYYY/ZZZZZ"

; -----------------------------------------------------------------------
; CHECKS
; -----------------------------------------------------------------------

["hello plugin"]
description="I sust wanna say hello"
function="hello"
params[message]="Here is ${USER}"
```

### Types of values

The binary uses the php function `parse_ini_file` - see 🌐 <https://www.php.net/manual/en/function.parse-ini-file.php>.

* The **section** is in brackets eg. `[<SECTION>]`
* In each section is a set of keys and values, separated by `=`
* **keys** (variable):

  * a string with letters, digits, underscore
  * Use multiple `<VARNAME>[]` to create an an array with list items
  * `<VARNAME>[<KEY>]` is used for slack notifications and one of the possible options for [check] -> params

* **values**

  * numbers of integer, float (no quoting)
  * strings in single quotes or double quotes
  * Specialty: In [check] -> params you can use JSON syntax: It is aquoted string using single quotes `'`. The JSON key and value must be quoted with double quotes.
  * Environment variables or PHP configuration values can be embedded using `${<VARMAME>}`; it works with unquoted value or double quoted strings but not inside single quotes (or JSON).

The values for each check are check specific. Have a look to the origin docs for each check - see 📗 <https://os-docs.iml.unibe.ch/appmonitor/PHP_client/Plugins/Checks/index.html>.

To have a minimal working example have a the folder `tests/configs` or here 🌐 <https://git-repo.iml.unibe.ch/iml-open-source/appmonitor-cli-client/-/tree/main/tests/configs?>. These ini files do NOT contain all supported keys.

## Exitcodes

The binary could stop and exit with non zero exitcode.

### amcli

| Exitcode | Description
| ---      | ---
| 0        | OK. An option was executed (help, list modules or checks) or the check was executed successfully
| 1        | include include_checks.php failed (php file only)
| 2        | include_checks.php failed (php file only)
| 3        | INI file was not given. Maybe just a missing `=` char in `--ini=<FILE>`?
| 4        | Given Ini file does not exist
| 5        | Given Ini file cannot be parsed
| 6        | Ini value `params=` is no JSON

### appmonitor-client class

| Exitcode | Description
| ---      | ---
| 10       | incomplete reponse data detected eg. no check, no result code
| 11       | Access denied: Ip restriction was set
| 12       | Access denied: No token or wrong token was given

### appmonitor-checks class

| Exitcode | Description
| ---      | ---
| 20       | Missing key in a given hash
| 21       | Mising value in a given hash
| 22       | Check not found. Check your `function`value
| 23       | Check didn't response a hash (=error in check)
| 24       | Check responded a too small hash (=error in check)
| 25       | The unit in a space value is unknown