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]

  • …

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

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.

See Also

◀ Main