An API client for apnscp
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.



Beacon provides a command-line interface to apnscp API + module introspection.



Beacon requires a key to be setup first in the control panel. Visit Dev > API Keys to generate a key. Beacon also requires at least PHP7, which restricts operation to v6.5+ platforms. Set the key by running exec with --key. Overwrite a previously configured key with -s:

beacon exec --key=somekey -s common_get_uptime



show service Display underlying code for given service


beacon show common_get_load

Example response

 * array get_load (void)
 * @privilege PRIVILEGE_ALL
 * @return array returns an assoc array of the 1, 5, and 15 minute
 * load averages; indicies of 1,5,15
 public function get_load()
     $fp = fopen('/proc/loadavg', 'r');
     $loadData = fgets($fp);
     $loadData = array_slice(explode(" ", $loadData), 0, 3);
     return array_combine(array(1, 5, 15), $loadData);


exec flags service [args, ...] Executes named service with optional args


beacon exec common_get_uptime

Example response

25 days 10 mins
Optional flags
  • format [json, bash, php] Alter output format
beacon exec --format=json common_get_load
beacon exec --format=php common_get_load
    [1] => 0.04
    [5] => 0.01
    [15] => 0.00
beacon exec --format=bash common_get_load
(["1"]="0.04" ["5"]="0.01" ["15"]="0.00")

Bash formatting can be used in shell scripting to populate variables, e.g.

declare -a load=`beacon exec --format=bash common_get_load`
echo ${load[1]}
  • set Set API key as default on exit

  • key key Specify an API key, key

  • keyfile file Specify a file, file that contains the API key to use. The file should be formatted as empty consisting of nothing but the key.

  • endpoint url Use the endpoint url instead of http://localhost:2082/soap.

arrays and hashes

Arrays and hashes are fed using a bracketed expression [] which may also be nested.

beacon e file_delete '[/tmp/a, /tmp/b]'
beacon e user_add_user "newuser" "newpassword" "some new user" '[imap:1,smtp:1]'

null and bool types

null and false may be passed verbatim to indicate a null or true/false parameter. To pass a string literal of the corresponding type, surround the argument with both single and double quotes,

Clear ACLs for user myuser

beacon e file_set_acls /home/foo myuser null

This is interchangeable, due to shell parsing mechanics, to,

beacon e file_set_acls /home/foo myuser "null"

Set read, write, execute for user "null"

beacon e file_set_acls /home/foo "'null'" 7

API reference

All modules are available through Modules that follow the naming XXX_Module are exposed as xxx, for example methods in File_Module are exposed as file_<method> and set_acls in File_Module is referenced as file_set_acls.