Command Line Interface (CLI)

The documentation assumes that When has been installed using the instructions provided in the installation guide. In this case the when command should be available from the command line, and could be invoked as follows:

when COMMAND [OPTIONS]

where COMMAND is one of the following:

  • config to launch the configuration utility, without staying resident (i.e. no system tray icon)

  • start to launch the resident whenever wrapper displaying a control icon on the system tray area

  • tool to launch one of the utilities that can help in the setup of a working environment

  • version to display version information.

More commands might be supported in the future. OPTIONS are the possible options, which have effect on specific commands:

  • -D/--dir-appdata PATH: specify the application data and configuration directory (default: %APPDATA%\Whenever on Windows, ~/.whenever on Linux)

  • -W/--whenever PATH: specify the path to the whenever executable (defaults to the one found in the PATH if any, otherwise exit with error, specific to start)

  • -L/--log-level LEVEL: specify the log level, all whenever levels are supported (default: info, specific to start)

  • -h/--help: print a brief help message about commands and options.

In order to know which options can be used for each command, when COMMAND --help can be invoked from the command line, where COMMAND is one of the commands described above.

Note

In order to simplify the usage of When, many values that could have been implemented as parameters are instead left as defaults that cannot be changed, at least for now, if not via direct intervention on the code.

This version of When uses poetry to manage dependencies and to provide a suitable environment for a source distribution, therefore after running poetry install in the project directory to install all necessary Python dependencies, When can also be launched as poetry run when COMMAND [OPTIONS].

Toolbox

The tool command provides various utilities that can help in the setup of When for a desktop environment. Each utility is invoked by means of a subcommand, which might possibly have variants. The following list explains the available subcommands and their options:

  • --install-whenever: downloads and installs the latest version of whenever for the current user

  • --create-icons: create the When desktop shortcuts (for both the configuration utility and for the resident application) for the current user in the Start or Applications menu – depending on the host platform; accepts the following modifiers

    • --autostart: (option) creates a shortcut that launches the resident version of When when the user logs in

    • --desktop: (option) also creates icons on the desktop[1]

  • --fix-config: fix legacy configuration files converting old item definitions to new ones

  • --check-config: check the configuration file for errors that might have been introduced by manually editing it

  • --install-lua: install a Lua script or library in the Lua specific subtree within the APPDATA directory

  • --upgrade-lua: upgrade a Lua script or library in the Lua specific subtree within the APPDATA directory: similar to --install-lua, but only works when a module already exists

  • …

  • --quiet: (option) applies to all the operations described above, and inhibits printing messages to the console.

Note

When will usually not check the configuration file if not requested to, in order to avoid excessive delay on startup: whenever itself performs a check for correctness and refuses to start when any error is found. The --check-config tool is provided to verify the configuration file in such cases, and to provide at least some clues about the errors, such as the line number at which the misconfigured item is found. The tool will try to report all errors found in the current configuration file. Since When normally generates correct configuration files, errors are generally introduced by manually editing the file itself. It is recommended, therefore, that the --check-config tool is launched after every manual change in the configuration file.

The subcommands cannot be combined. The whenever installation step should be performed first if there is no working copy of the core scheduler on the system.

Output of the Configuration Check Tool

The --check-config tool can be useful to get help on errors in configuration files which have been manually edited: normally, files generated by the When configuration application should be correct and consistent,[2] however TOML files are known for being easily modifiable using a simple text editor, and When tries to produce configuration files which are as readable as possible, in order to allow for simple direct modifications according to the user preferences. The tool is usually invoked with no parameters, as it is designed to check the configuration file in use (the one in APPDATA), and provides a verbose output:

> when tool --check-config

When - ERROR: The following errors have been found in configuration file `[...]/whenever.toml`
When - ERROR: * ConfigurationError Cond_AFK01@29 (idle_seconds): `invalid value: some`
When - ERROR: Operation failed.

which is the result when the mentioned configuration file contains the following snippet at line 29:

[[condition]]
name = "Cond_AFK01"
type = "idle"
tasks = ["Task_TRACE"]
recurring = true
idle_seconds = "some"

where the idle_seconds parameter was expected to be an integer, and a string is provided. In other words, the tool reports (or at least tries to, in case of errors that are specifically related to items):

  • the item name, followed by an @ sign and the line number where its definition begins,

  • the entry that holds an unexpected value, or that is missing although required,

  • a message stating what is wrong (an unexpected or missing value).

Other errors can be reported, for instance TOML syntax errors, along with the coordinates needed to locate them in the file.

The --check-config tool, moreover, tries to report as many errors as possible: so, in case of a file which is affected by more than one error, more than an error line will be reported.

Warning

The error lines (the ones that begin with the When - ERROR: * ConfigurationError prefix) are not translated to the current locale.

Note

If an error is detected in an event based condition or in a task, the corresponding item will not be registered: this has the secondary effect that all items that reference it will be invalid, since the name of the incorrect item that will not be considered a valid name. For instance, if a task named Task01 is incorrectly configured, it will not be loaded as a task: this means, that all conditions that have Task01 in their execution list, will report Task01 as an invalid value.

See Also

◀ Main