---
title: "Scripting with Beacon"
date: "2017-02-12"
category: "control-panel"
slug: "scripting-with-beacon"
---

![](kb-image:beacon.png)

Beacon is a command-line scripting companion to the [[logging-into-the-control-panel]]. It provides a simple interface to interact with over [2,000 API commands](http://api.apnscp.com/docs/) exposed in ApisCP. Beacon is also available on [GitHub](https://github.com/apisnetworks/beacon).

## Getting Started

Beacon requires an API key for authentication. Create one in the [[logging-into-the-control-panel]] under **Dev** > **API Keys**.

On first use, specify the key with `--key`:

`beacon exec --key=AAAA-BBBB-CCCC-DDDD common_get_web_server_name`

If successful, your domain name will be printed.

After the initial setup, `--key` can be omitted. To update the key later, pass `--key=...` with `--set`. To run Beacon from a remote machine, also specify `--endpoint=https://launchpad.url.in.the.panel:2083/soap` (your endpoint URI is shown in **Dev** > **API Keys**).

## Command Format

Each command uses the `exec` imperative followed by the module and method name in lowercase, separated by underscores. For example, the `get_load` method in the `Common` module becomes:

`beacon exec common_get_load`

This returns an array of 1, 5, and 15-minute load averages.

## Parameters

Parameters follow the command invocation. Standard shell [special characters](http://tldp.org/LDP/abs/html/special-chars.html) and [variable interpolation](http://tldp.org/LDP/abs/html/parameter-substitution.html) rules apply.

- Use `0` instead of `false` for boolean values
- Omitted parameters must be specified as an empty string (`""`)
- Arrays and hashes are enclosed in `[]` and can be nested
- Hash keys are postfixed with a colon

### Primitive Examples

`beacon exec sql_create_mysql_database test beacon exec common_get_service_value siteinfo admin_user beacon exec file_chown /var/www/myfile.txt myadmin 1`

### Array/Hash Examples

`beacon exec file_set_acls /var/www/ myotheruser rwx [recursive:1] beacon exec sql_create_mysql_database foobar beacon exec wordpress_update_themes mydomain.com "" [avada,twentyseventeen]`

## Output Formats

By default, Beacon outputs in human-readable format using [print_r](http://php.net/print_r). Alternative formats:

`$ beacon exec --format=json common_get_load` `{"1":"0.52","5":"0.82","15":"0.94"} $ beacon exec --format=bash common_get_load` `(['1']='0.47' ['5']='0.81' ['15']='0.94')`

No trailing EOL marker is included for ease of parsing.

## Chaining Commands

Beacon's real power comes from combining it with shell scripting.

### Checking if All WordPress Domains Are Current

Iterate over all domains and update WordPress if not current:

```
# () also works in lieu of declare -a...
```

### Create an Addon Domain and Install a Web Application

Creates a new addon domain, then installs WordPress, Drupal, or any [[detecting-a-web-application]]. `${n,,}` converts the parameter to lowercase in bash v4+ using [case modifiers](http://tldp.org/LDP/abs/html/parameter-substitution.html#PARAMSUBREF).

function newdomain {
    domain=${1,,}
    app=${2,,}
    path=/var/www/${domain}
    beacon exec aliases\_add\_shared\_domain $domain $path
    beacon exec aliases\_synchronize\_changes
    beacon exec ${app}\_install $domain 
}

## Introspection

Use `show` for code introspection when a command's purpose is unclear. Introspection fetches source code from the [GitHub repository](https://github.com/apisnetworks/apnscp-modules/tree/master/modules) and uses reflection to display the method signature.

`beacon show common_get_load`

/\*\*
 \* 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);
        fclose($fp);
        $loadData = array\_slice(explode(" ", $loadData), 0, 3);
        return array\_combine(array(1, 5, 15), $loadData);
}
