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:
- Reference for Command-Line Utilities, Plesk for Linux
- Reference for Command-Line Utilities, Plesk for Microsoft Windows
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.