pmctl

pmctl: control tool.

Synopsis

pmctl
-browse
-format ( plist json )
-h
-help
-legal
-netrc path
-u URL
-url URL
-v
-verbose
-version

Description

pmctl is a tool for managing DssW Power Manager.

pmctl is used to connect to and control Power Manager. pmctl is the main command line tool for interacting with local and remote Power Manager instances.

pmctl can send requests to Power Manager. Responses can be displayed in common script friendly formats.

If no URL is provided, pmctl will connect to the default instance of Power Manager. The default is typically the local instance of Power Manager.

A provided URL must include a pm:// or dnssd:// scheme. The file path form is used to connect with older local versions of Power Manager through a UNIX domain socket.

IPv6 shorthand notation is supported. The IPv6 loopback address can be written as [::1].

bash$ ./pmctl
bash$ ./pmctl -u pm://192.168.1.40:4567
bash$ ./pmctl -u pm://localhost:4567
bash$ ./pmctl -u pm://[::1]:4567
bash$ ./pmctl -u pm:/var/tmp/uk.co.dssw.powermanager/pmd
bash$ ./pmctl -u dnssd://Mac-Pro
bash$ ./pmctl -u dnssd://Mac-Pro.local.

A range of URL schemes are supported by pmctl

pmctl can connect to Bonjour/ZeroConf advertised Power Manager services. Use the dnssd:// scheme to provide the service name to resolve and connect to.

By default, Bonjour service name resolution occurs within the local. domain. Append the domain to the URL dnssd://Mac-Pro.other-domain. to provide an alternative domain to resolve service names with.

bash$ ./pmctl build.version

Get the version details of the local Power Manager instance.

Sets of parameters can be associated with a request. A parameter consists of a name and value pair.

name=value

Base parameter format.

bash$ ./pmctl scheduler.setenabled enabled=true

Enable the scheduler with a request and parameter.

Parameters containing spaces must be quoted to avoid the shell splitting the contents:

bash$ ./pmctl scheduler.remove 'unique ID=Weekend Sleep'

Parameters with spaces must be quoted.

Preprocessed Parameters

Parameters may be preprocessed using parentheses. Preprocessed parameters expand the range of input pmctl can use when building a request. They allow for parameters to be read from files, remote resources, and for pass phrases to be securely requested from the command line.

Some complex parameters must be preprocessed. These parameters include those that require structures or arrays.

bash$ ./pmctl scheduler.set event=(plist:file:///Users/Shared/event.plist)

Set an event using the contents of a local property list file.

Permitted formats include:

  • json
  • plist
  • raw
  • text
Remote Parameters

A parameter can be fetched from a file path or a URL:

bash$ ./pmctl eventstore.store events=(plist:https://example.com/events.plist)

Using a remote property list as a parameter.

Remote parameters can also be encoded as plain text or JavaScript Object Notation (JSON). These formats contain less structured information and will likely require additional type coercion:

name=(json:URL)
name=(plain:URL)

Alternative parameter formats.

The URL may refer to local or remote resources:

bash$ ./pmctl scheduler.set event=(plist:file:///Users/Shared/event.plist)
bash$ ./pmctl scheduler.set event=(plist:http://www.example.com/event.plist)
bash$ ./pmctl scheduler.set event=(plist:https://www.example.com/event.plist)

A range of URL schemes are supported for getting property lists.

URLs may be escape encoded. Relative file scheme URLs are evaluated using the current working directory as the base location.

Raw Parameters

A parameter may need to include contents that match pmctl's preprocessing format. To avoid preprocessing content, use the raw preprocessor:

-p 'name=(raw:contents)'

Base raw parameter format.

The brackets and prefixed raw will be removed, but the contents will be untouched and passed through as the parameter.

If an event has the unique ID (plist:file:///tmp/), the following command will issue an appropriate remove request:

bash$ ./pmctl -r scheduler.remove -p 'unique ID=(raw:(plist:file:///tmp/))'

Remove an event with the unique ID: (plist:file:///tmp/).

Multiple Requests

Multiple requests can be sent by appending the requests to the command. A single connection is created and the requests are issued in the order provided on the command line.

pmctl sends one request at a time. pmctl may interrupt the requests, if authentication is required by the Scheduler. In this case, the authentication must be completed successfully before the remaining requests are sent.

Responses to multiple requests are grouped and output as a dictionary or an associative array:

bash$ ./pmctl build.version notifications.warningperiod notifications.notifyperiod
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
    <dict>
        <key>build.version</key>
        <string>uk.co.dssw.powermanager.pmd v5.0.0</string>
        <key>notifications.notifyperiod</key>
        <integer>900</integer>
        <key>notifications.warningperiod</key>
        <integer>3</integer>
    </dict>
</plist>

Multiple requests are supported. Responses are returned as dictionaries.

Character Encoding

All character encoding and input is assumed to be UTF8. Providing input in other encodings may can authentication to fail.

UTF8 encoding is the default for macOS's Terminal.app application.

Parameter Coercion

Parameters need to passed to Power Manager in specific formats. All parameters provided directly from command line arguments are strings; in many cases strings are not the appropriate format.

Type coercion is limited in the possible conversions that can be performed. Where a conversion is not possible, the original parameter is left untouched. In this situation the request is expected to fail with an error message explaining which parameter is invalid.

pmctl can coerce parameters manually by extending the request format.

bash$ ./pmctl scheduler.setenabled enabled:boolean=true

Coerce the parameter enabled from a string to a boolean.

To coerce a parameter, insert a final parameter type into the request before the equals symbol. Supported types include:

  • boolean
  • date
  • integer
  • real
  • string

Return Values

pmctl returns EXIT_SUCCESS, 0 if a connection is established. EXIT_FAILURE is returned if no connection could be established, or authentication failed.

The return value can be used to test if Power Manager is available locally, or at a specified address.

#!/bin/sh

`./pmctl`
if [ "$?" -ne "0" ]; then
  echo "Power Manager is not available"
else
  echo "Power Manager is available"
fi

Shell script to test pmctl's return value.

#!/bin/sh

`./pmctl -u pm://192.168.1.1:1234` && ( echo "Power Manager is available" ) || ( echo "Power Manager is not available" )

One line shell script to test pmctl's return value.

Files

Back to the previous page.