kibitzr reads configuration from kibitzr.yml file. It tries to find it in following places:

  1. ./kibitzr.yml - current working directory.

  2. ~/.config/kibitzr/kibitzr.yml

  3. ~/kibitzr.yml

kibitzr-creds.yml can be used to store credentials, it must be placed in the same directory as kibitzr.yml.


kibitzr serves list of checks.

Each check may have a name. If name is present it must be unique. If no name is provided, it will be auto-generated.

The name is used in notifications and internally as a check identifier.

Check may have url. If it is provided, it will be used to fetch data. Optionally verify-cert can be set to False to skip verificaiton of the SSL certificate. Alternativelly data can be fetched by script, which is an arbitrary shell script.

Check will be executed every period seconds and/or on every schedule. See Schedule documentation for a complete list of possibilities.

Fetched data from url (or script output) is passed to a pipeline of transformations defined under transform key. See Transforms documentation for a complete list of supported transformations.

Finally transformed data is passed to a list of notifiers defined under notify key. See Notifier documentation for a complete list of supported notifiers.

Kibitzr supports browser interactions. They can be activated by using any of keys:

  1. delay - number of seconds to wait after page loaded in browser to process JavaScript.

  2. scenario - python scenario acting on selenium driver after page load.

  3. form - shorthand for simple selenium scenarios.

Browser interaction is a strong side of Kibitzr and a tough article in itself. Please refer to Browser automation documentation.

Environment variables

Kibitzr provides read access to environment variables in a number of ways.

Inside Python support scripts, use Pythonic builtin module os:

import os

In shell scripts use bash syntax:

echo ${NAME}

Jinja templates have env dictionary in their context:

{{ env.NAME }}

kibitzr-creds.yml supports bash-like environment interpolation provided by yamlenv library:

    username: ${ USERNAME }
    password: ${ PASSWORD }

Example break down

Let’s start with something simple. It’s not very useful check, but it shows the basics.

  - name: Current Time
      - css: "span#theTime"
      - text
      - python: print(content)
    period: 15

Copy paste it to your kibitzr.yml and launch kibitzr. You will see something like this:

$ kibitzr once
2017-03-28 22:02:39,465 [INFO] kibitzr.checker: Fetching Current Time at
2017-03-28 22:02:39,687 [INFO] kibitzr.notifier.custom: Executing custom notifier
10:02:39 pm
2017-03-28 22:02:39,687 [INFO] kibitzr.main: Scheduling checks for 'Current Time' every 15 seconds
2017-03-28 22:02:39,688 [INFO] kibitzr.main: Starting infinite loop
2017-03-28 22:02:54,705 [INFO] schedule: Running job Every 15 seconds do check() (last run: [never], next run: 2017-03-28 22:02:54)
2017-03-28 22:02:54,705 [INFO] kibitzr.checker: Fetching Current Time at
2017-03-28 22:02:54,823 [INFO] kibitzr.notifier.custom: Executing custom notifier
10:02:54 pm

Let’s follow the configuration file line-by-line to see how it works.

On the first line we define a dictionary key checks:


Then, starting with indentation and dash goes the name of the first check:

- name: Current Time

It’s an arbitrary string, the only constraint is that it must be unique within the checks list.

Right after name, we define URL:


Please note, that all keys are in lower case.

So far so good, we came to transformations:

  - css: "span#theTime"
  - text

transform value must be a list (as denoted by dashes). Please note how list items indentation is deeper, than of transform.

Each transform item can be a simple transform name (like text, which extracts text from HTML), or a name: argument pair (like css: "#qlook > div" which crops HTML using CSS selector "#qlook > div")

As you can see, we first crop whole page to a single HTML tag and then extract plain text from it.

Having all the hard job behind, we came to notification settings. kibitzr supports many different notifiers, but here we are using the one, that does not require credentials management - arbitrary Python script.

  - python: print(content)

It is exactly the code, that produced

10:02:39 pm

in the kibitzr output.

Last line of configuration file is the period:

period: 15

The number of seconds to wait between (start of) checks. Kibitzr understands time to the extent, you can write 1 hour instead of 3600. For the more complete list of available formats refer to pytimeparse docs.