# Command Line Interface (CLI)

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

```shell
when COMMAND [OPTIONS]
```

where `COMMAND` is one of the following:

- `config` to launch the [configuration utility](cfgform.md), without staying resident (i.e. no system tray icon)
- `start` to launch the resident **whenever** [wrapper](tray.md) 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](https://python-poetry.org/) 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](configfile.md#legacy-configuration-files) 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_](appdata.md) directory
* `--upgrade-lua`: upgrade a _Lua_ script or library in the _Lua_ specific subtree within the [_APPDATA_](appdata.md) 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_](appdata.md)), and provides a verbose output:

```text
> 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_:

```toml
[[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

* [Installation](install.md)
* [Configuration Utility](cfgform.md)
* [Resident Wrapper](tray.md)


[`◀ Main`](main.md)


[^1]: on some Linux desktop (for example, the most recent versions of Gnome) the deployment of launcher files in the `~/Desktop` subfolder is not honored as a way to create desktop icons, thus the `--desktop` option is actually executed, but has no effect.
[^2]: with the possible exception of files generated using old versions of **When** that produce configuration files in deprecated formats.