pmctl: control tool.
pmctl
-browse
-format ( plist
json
)
-h
-help
-legal
-netrc path
-u URL
-url URL
-v
-verbose
-version
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.
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
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.
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 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.
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.
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
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.
Power Manager.app/Contents/Tools/pmctl
Back to the previous page.