Command-Line Interface

Some extensions may use the command-line utilities that Plesk provides to administrators as an alternative to performing operations from the GUI. The Command-Line Interface (CLI) has the same functions as XML API, but an operation output is provided as a plain text rather than an XML tree. Learn more about the command-line utilities in the following documents:

To perform a CLI call, use the pm_ApiCli class.

Executing Utilities

A command-line call is performed by the method:

The first argument is the utility name, and the second argument is the array of options and their values. The optional third argument specifies what kind of information about the utility’s execution results is returned.

Note: For Plesk versions 12.5 and older, the pm_ApiCli::call can only be called from command-line scripts, and not via operations in the Plesk GUI.

Example: Retrieving the license key information

The following example retrieves information about the current Plesk license key:

$result = pm_ApiCli::call('keyinfo', ['-l']);
var_dump($result);

The output should be similar to the following:

array(3) {
    ["code"] =>
        int(0)

    ["stdout"] =>
        string(447) "plesk_key_id: 0
        license_update_date: 20350101
        lim_date: 20120501
        lim_cl: -1
        ...
        "

    ["stderr"] =>
        string(0) ""
}

In more complex situations, divide a call into arguments and add each argument as an array item. For example:

customer --create johnusername -name "John Doe" -passwd sample -country US -notify false

should be transformed to:

pm_ApiCli::call('customer', ['--create', 'johnusername', '-name', 'John Doe', '-passwd', 'sample', '-country', 'US', '-notify', 'false']);
Example: Processing utility execution results

It is possible to choose what kind of information about the utility's execution is returned by the call. To do that, specify the type of return value in the last parameter to the call(), like this:

$result = pm_ApiCli::call('license', ['--check-installed-license'], pm_ApiCli::RESULT_CODE);

In this example, the $result variable will be assigned the error code generated by the execution of 'license' with parameter '--check-installed-license', which is ‘0’ if the installed license key is valid and ‘1’ otherwise.

All available types of return values are described here: pm_ApiCli Constants.

Note: If no return value type is specified, the default returned value is RESULT_EXCEPTION. Before Plesk 17, the default return value was RESULT_FULL. This change may need to be reflected in extensions that support Plesk versions 12.5 and older as well as Plesk 17 and later.

If the utility’s execution results in error code ‘0’, using RESULT_EXCEPTION returns the same array of values as does RESULT_FULL (code, stdout, stderr). But if the resulting error code is not ‘0’, using RESULT_EXCEPTION causes an exception (pm_Exception_ResultException) to be thrown.

Executing Privileged Utilities

The directory /<product-root>/admin/bin/ contains utilities that are run with elevated privileges. In addition to this, an extension can bring some utilities that should be run with elevated privileges. Such utilities are placed in the directory /<product-root>/admin/bin/modules/$MODULE_NAME.

Note: For Plesk versions 12.5 and older, privileged utilities are only available in Plesk for Linux.

You can run such utilities by using the method:

For example:

$result = pm_ApiCli::callSbin('my-utility');
var_dump($result);

By default, the utility called my-utility will be searched for in the directory /<product-root>/admin/bin/modules/$MODULE_NAME. If the utility is not found, it will then be searched for in the directory /usr/local/psa/admin/bin/.

Note: The same as with call(), callSbin() accepts the optional third argument that specifies what kind of information about the privileged utility’s execution results is returned.

 

Leave your feedback on this topic here

If you have questions or need support, please visit the Plesk forum or contact your hosting provider.
The comments below are for feedback on the documentation only. No timely answers or help will be provided.