pdtools CLI Reference¶
pdtools¶
Paradrop command line utility.
pdtools [OPTIONS] COMMAND [ARGS]...
chute¶
Utilities for developing chutes.
These commands all operate on a chute project in the current working directory. Remember, that all chutes must have a paradrop.yaml file in the top-level directory. You can create one interactively with the initialize command.
pdtools chute [OPTIONS] COMMAND [ARGS]...
add-wifi-ap¶
Add a WiFi AP to the chute configuration.
ESSID must be between 1 and 32 characters in length. Spaces are allowed if you enclose the argument in quotation marks.
pdtools chute add-wifi-ap [OPTIONS] ESSID
Options
-
--password
<password>
¶ Password for the network, must be at least 8 characters if specified.
-
--force
¶
Overwrite an existing section in the configuration file.
Arguments
-
ESSID
¶
Required argument
enable-web-service¶
Configure chute for providing a web service.
This command adds information to the paradrop.yaml file about a web server that runs as part of the chute. PORT should be the port that the chute code listens on. Paradrop will forward external requests to this port. If the chute runs multiple services, then SERVICE should be used to indicate the name of the service that runs the web server. For most chutes, the default “main” will be appropriate.
pdtools chute enable-web-service [OPTIONS] PORT
Options
-
-s
,
--service
<service>
¶ Name of service in chute which runs the web server.
Arguments
-
PORT
¶
Required argument
export-configuration¶
Export chute configuration in JSON or YAML format.
The configuration format used by the cloud API is slightly different from the paradrop.yaml file. This command can export a JSON object in a form suitable for installing the chute through the cloud API.
The config object will usually be used in an envelope like the following: {
“updateClass”: “CHUTE”, “updateType”: “update”, “config”: { config-object }
}
pdtools chute export-configuration [OPTIONS]
Options
-
-f
,
--format
<format>
¶ Format (json or yaml)
initialize¶
Interactively create a paradrop.yaml file.
pdtools chute initialize [OPTIONS]
Options
-
--legacy
¶
Create a single-service chute using older syntax.
set¶
Set a value in the paradrop.yaml file.
PATH must be a dot-separated path to a value in the paradrop.yaml file, such as “config.web.port”. VALUE will be interpreted as a string, numeric, or boolean type as appropriate.
Changing values inside a list is not currently supported. For that you will need to edit the file directly.
Example: set config.web.port 80
pdtools chute set [OPTIONS] PATH VALUE
Arguments
-
PATH
¶
Required argument
-
VALUE
¶
Required argument
validate¶
Validate the paradrop.yaml file.
A note about versions: this command validates the chute configuration against the current rules for the installed version of pdtools. If the chute is to be installed on a Paradrop node running a different version, then this command may not be reliable for determining compatibility.
pdtools chute validate [OPTIONS]
cloud¶
Access services provided by a cloud controller.
By default the cloud controller is assumed to be paradrop.org. This can be configured through the environment variable PDSERVER_URL.
pdtools cloud [OPTIONS] COMMAND [ARGS]...
claim-node¶
Take ownership of a node by using a claim token.
TOKEN is a hard-to-guess string that the previous owner would have configured when setting the node’s status as orphaned.
pdtools cloud claim-node [OPTIONS] TOKEN
Options
-
-n
,
--name
<name>
¶ Name of the node
Arguments
-
TOKEN
¶
Required argument
create-node¶
Create a new node to be tracked by the controller.
NAME must be unique among the nodes that you own and may only consist of lowercase letters, numbers, and hyphens. It must also begin with a letter.
pdtools cloud create-node [OPTIONS] NAME
Options
-
--orphaned
,
--not-orphaned
¶
Allow another user to claim the node.
-
--claim
<claim>
¶ Claim token required to claim the node.
Arguments
-
NAME
¶
Required argument
delete-node¶
Delete a node that is tracked by the controller.
NAME must be the name of a node that you own.
pdtools cloud delete-node [OPTIONS] NAME
Arguments
-
NAME
¶
Required argument
describe-node¶
Get detailed information about an existing node.
NAME must be the name of a node that you own.
pdtools cloud describe-node [OPTIONS] NAME
Arguments
-
NAME
¶
Required argument
edit-node-description¶
Interactively edit the node description and save.
NAME must be the name of a node that you own.
Open the text editor specified by the EDITOR environment variable with the current node description. If you save and exit, the changes will be applied to the node.
pdtools cloud edit-node-description [OPTIONS] NAME
Arguments
-
NAME
¶
Required argument
group-add-node¶
Add a node to a group for other members to access.
GROUP must be the string ID of a group. NODE must be the name of a node that you control.
pdtools cloud group-add-node [OPTIONS] GROUP NODE
Arguments
-
GROUP
¶
Required argument
-
NODE
¶
Required argument
import-ssh-key¶
Add an authorized key from a public key file.
PATH must be a path to a public key file, which corresponds to a private key that SSH can use for authentication. Typically, ssh-keygen will place the public key in “~/.ssh/id_rsa.pub”.
pdtools cloud import-ssh-key [OPTIONS] PATH
Arguments
-
PATH
¶
Required argument
login¶
Interactively login to your user account on the controller.
Authenticate with the controller using account credentials that you created either through the website or with the register command. Typically, the username will be your email address.
pdtools cloud login [OPTIONS]
rename-node¶
Change the name of a node.
NAME must be the name of a node that you control. NEW_NAME is the desired new name. It must adhere to the same naming rules as for the create-node command, namely, it must begin with a letter and consist of only lowercase letters, numbers, and hyphen.
pdtools cloud rename-node [OPTIONS] NAME NEW_NAME
Arguments
-
NAME
¶
Required argument
-
NEW_NAME
¶
Required argument
device¶
(deprecated) Sub-tree for configuring a device.
These commands are deprecated. Please use the equivalent commands under pdtools node –help.
pdtools device [OPTIONS] ADDRESS COMMAND [ARGS]...
Arguments
-
ADDRESS
¶
Required argument
audio¶
Control device audio properties.
pdtools device audio [OPTIONS] COMMAND [ARGS]...
load-module¶
Load a module.
pdtools device audio load-module [OPTIONS] NAME
Arguments
-
NAME
¶
Required argument
sink¶
Configure audio sink.
pdtools device audio sink [OPTIONS] SINK_NAME COMMAND [ARGS]...
Arguments
-
SINK_NAME
¶
Required argument
chute¶
Sub-tree for configuring a chute.
pdtools device chute [OPTIONS] CHUTE COMMAND [ARGS]...
Arguments
-
CHUTE
¶
Required argument
edit-environment¶
Interactively edit the chute environment vairables.
pdtools device chute edit-environment [OPTIONS]
network¶
Sub-tree for accessing chute network.
pdtools device chute network [OPTIONS] NETWORK COMMAND [ARGS]...
Arguments
-
NETWORK
¶
Required argument
shell¶
Open a shell inside a chute.
This requires you to have enabled SSH access to the device and installed bash inside your chute.
pdtools device chute shell [OPTIONS]
hostconfig¶
Sub-tree for the host configuration.
pdtools device hostconfig [OPTIONS] COMMAND [ARGS]...
pdconf¶
Access the pdconf subsystem.
pdconf manages low-level configuration of the Paradrop device. These commands are implemented for debugging purposes and are not intended for ordinary configuration purposes.
pdtools device pdconf [OPTIONS] COMMAND [ARGS]...
provision¶
Provision the router.
pdtools device provision [OPTIONS] ROUTER_ID ROUTER_PASSWORD
Options
-
--server
<server>
¶
-
--wamp
<wamp>
¶
Arguments
-
ROUTER_ID
¶
Required argument
-
ROUTER_PASSWORD
¶
Required argument
group¶
(deprecated) Manage a user group.
These commands are deprecated. Please use the equivalent commands under pdtools cloud –help.
pdtools group [OPTIONS] GROUP_ID COMMAND [ARGS]...
Arguments
-
GROUP_ID
¶
Required argument
list-groups¶
(deprecated) List user groups.
Please use pdtools cloud list-groups.
pdtools list-groups [OPTIONS]
node¶
Manage a Paradrop edge compute node.
These commands respect the following environment variables:
PDTOOLS_NODE_TARGET Default target node name or address.
pdtools node [OPTIONS] COMMAND [ARGS]...
Options
-
-t
,
--target
<target>
¶ Target node name or address
connect-snap-interfaces¶
Connect all interfaces for installed snaps.
pdtools node connect-snap-interfaces [OPTIONS]
create-user¶
Create local Linux user connected to Ubuntu store account.
EMAIL must be an email address which is registered as Ubuntu One account. The name of the local account that is created will depend on the email address used. If in doubt, use “info@paradrop.io”, which will result in a user named “paradrop” being created.
pdtools node create-user [OPTIONS] EMAIL
Arguments
-
EMAIL
¶
Required argument
describe-audio¶
Display audio subsystem information.
Display information from the local PulseAudio server such as the default source and sink.
pdtools node describe-audio [OPTIONS]
describe-chute¶
Display information about a chute.
CHUTE must be the name of an installed chute.
pdtools node describe-chute [OPTIONS] CHUTE
Arguments
-
CHUTE
¶
Required argument
describe-chute-cache¶
Show internal details from a chute installation.
CHUTE must be the name of an installed chute.
This information is intended for Paradrop daemon developers for debugging purposes. The output is not expected to remain stable between Paradrop versions.
pdtools node describe-chute-cache [OPTIONS] CHUTE
Arguments
-
CHUTE
¶
Required argument
describe-chute-configuration¶
Display configuration of a chute.
CHUTE must be the name of an installed chute.
This information corresponds to the “config” section in a chute’s paradrop.yaml file.
pdtools node describe-chute-configuration [OPTIONS] CHUTE
Arguments
-
CHUTE
¶
Required argument
describe-chute-network-client¶
Display information about a network client.
CHUTE must be the name of an installed chute. NETWORK must be the name of one of the chute’s configured networks. Typically, this will be “wifi”. CLIENT identifies the network client, such as a MAC address.
pdtools node describe-chute-network-client [OPTIONS] CHUTE NETWORK CLIENT
Arguments
-
CHUTE
¶
Required argument
-
NETWORK
¶
Required argument
-
CLIENT
¶
Required argument
describe-pdconf¶
Show status of the pdconf subsystem.
This information is intended for Paradrop daemon developers for debugging purposes.
pdtools node describe-pdconf [OPTIONS]
describe-provision¶
Show provisioning status of the node.
This shows whether the node is associated with a cloud controller, and if so, its identifier.
pdtools node describe-provision [OPTIONS]
describe-settings¶
Show node settings.
These are settings that paradrop reads during startup and configure certain behaviors. They can only be modified through environment variables or the settings.ini file.
pdtools node describe-settings [OPTIONS]
edit-chute-configuration¶
Interactively edit the chute configuration and restart it.
CHUTE must be the name of an installed chute.
Open the text editor specified by the EDITOR environment variable with the current chute configuration. If you save and exit, the new configuration will be applied and the chute restarted.
pdtools node edit-chute-configuration [OPTIONS] CHUTE
Arguments
-
CHUTE
¶
Required argument
edit-chute-variables¶
Interactively edit a chute’s environment variables and restart it.
CHUTE must be the name of an installed chute.
Open the text editor specified by the EDITOR environment variable with the current chute environment variables. If you save and exit, the new settings will be applied and the chute restarted.
pdtools node edit-chute-variables [OPTIONS] CHUTE
Arguments
-
CHUTE
¶
Required argument
edit-configuration¶
Interactively edit the node configuration and apply changes.
Open the text editor specified by the EDITOR environment variable with the current node configuration. If you save and exit, the new configuration will be applied to the node.
pdtools node edit-configuration [OPTIONS]
export-configuration¶
Display the node configuration in the desired format.
pdtools node export-configuration [OPTIONS]
Options
-
-f
,
--format
<format>
¶ Format (json or yaml)
generate-configuration¶
Generate a new node configuration based on detected hardware.
The new configuration is not automatically applied. Rather, you can save it to file and use the import-configuration command to apply it.
pdtools node generate-configuration [OPTIONS]
Options
-
-f
,
--format
<format>
¶ Format (json or yaml)
import-configuration¶
Import a node configuration from file and apply changes.
PATH must be a path to a node configuration file in YAML format.
pdtools node import-configuration [OPTIONS] PATH
Arguments
-
PATH
¶
Required argument
import-ssh-key¶
Add an authorized key from a public key file.
PATH must be a path to a public key file, which corresponds to a private key that SSH can use for authentication. Typically, ssh-keygen will place the public key in “~/.ssh/id_rsa.pub”.
pdtools node import-ssh-key [OPTIONS] PATH
Options
-
-u
,
--user
<user>
¶ Local username
Arguments
-
PATH
¶
Required argument
install-chute¶
Install a chute from the working directory.
Install the files in the current directory as a chute on the node. The directory must contain a paradrop.yaml file. The entire directory will be copied to the node for installation.
pdtools node install-chute [OPTIONS]
Options
-
-d
,
--directory
<directory>
¶ Directory containing chute files
list-audio-modules¶
List modules loaded by the audio subsystem.
pdtools node list-audio-modules [OPTIONS]
list-chute-network-clients¶
List clients connected to the chute’s network.
CHUTE must be the name of an installed chute. NETWORK must be the name of one of its configured networks. Typically, this will be called “wifi”.
pdtools node list-chute-network-clients [OPTIONS] CHUTE NETWORK
Arguments
-
CHUTE
¶
Required argument
-
NETWORK
¶
Required argument
list-chute-networks¶
List networks configured by a chute.
CHUTE must be the name of an installed chute.
pdtools node list-chute-networks [OPTIONS] CHUTE
Arguments
-
CHUTE
¶
Required argument
list-snap-interfaces¶
List interfaces for snaps installed on the node.
pdtools node list-snap-interfaces [OPTIONS]
list-ssh-keys¶
List keys authorized for SSH access to the node.
pdtools node list-ssh-keys [OPTIONS]
Options
-
-u
,
--user
<user>
¶ Local username
load-audio-module¶
Load a module into the audio subsystem.
MODULE must be the name of a PulseAudio module such as “module-loopback”.
pdtools node load-audio-module [OPTIONS] MODULE
Arguments
-
MODULE
¶
Required argument
login¶
Interactively log in using the local admin password.
Authenticate with the node using the local username and password. Typically, the username will be “paradrop”. The password can be set with the set-password command.
pdtools node login [OPTIONS]
open-chute-shell¶
Open a shell inside the running chute.
CHUTE must be the name of a running chute.
This requires you to have enabled SSH access to the device and installed bash inside your chute.
Changes made to files inside the chute may not be persistent if the chute or the node is restarted. Only changes to files in the “/data” directory will be preserved.
pdtools node open-chute-shell [OPTIONS] CHUTE
Options
-
-s
,
--service
<service>
¶ Service belonging to the chute
Arguments
-
CHUTE
¶
Required argument
provision¶
Associate the node with a cloud controller.
ID and KEY are credentials that can be found when creating a node on the controller, either through the website or through pdtools cloud create-node. They may also be referred to as the Router ID and the Router Password.
pdtools node provision [OPTIONS] ID KEY
Options
-
-c
,
--controller
<controller>
¶ Cloud controller endpoint
-
-w
,
--wamp
<wamp>
¶ WAMP endpoint
Arguments
-
ID
¶
Required argument
-
KEY
¶
Required argument
remove-chute¶
Remove a chute from the node.
CHUTE must be the name of an installed chute.
pdtools node remove-chute [OPTIONS] CHUTE
Arguments
-
CHUTE
¶
Required argument
remove-chute-network-client¶
Remove a connected client from the chute’s network.
CHUTE must be the name of an installed chute. NETWORK must be the name of one of the chute’s configured networks. Typically, this will be “wifi”. CLIENT identifies the network client, such as a MAC address.
Only implemented for wireless clients, this effectively kicks the client off the network.
pdtools node remove-chute-network-client [OPTIONS] CHUTE NETWORK CLIENT
Arguments
-
CHUTE
¶
Required argument
-
NETWORK
¶
Required argument
-
CLIENT
¶
Required argument
restart-chute¶
Restart a chute.
CHUTE must be the name of an installed chute.
pdtools node restart-chute [OPTIONS] CHUTE
Arguments
-
CHUTE
¶
Required argument
set-configuration¶
Change a node configuration value and apply.
PATH must be a dot-separated path to a value in the node configuration, such as “system.onMissingWiFi”. VALUE will be interpreted as a string, numeric, or boolean type as appropriate.
Changing values inside a list is not currently supported. Use edit-configuration instead.
pdtools node set-configuration [OPTIONS] PATH VALUE
Arguments
-
PATH
¶
Required argument
-
VALUE
¶
Required argument
set-password¶
Change the local admin password.
Set the password required by pdtools node login and the local web-based administration page.
pdtools node set-password [OPTIONS]
set-sink-volume¶
Configure audio sink volume.
SINK must be the name of a PulseAudio sink. VOLUME should be one (applied to all channels) or multiple (one for each channel) floating point values between 0 and 1.
pdtools node set-sink-volume [OPTIONS] SINK [VOLUME]...
Arguments
-
SINK
¶
Required argument
-
VOLUME
¶
Optional argument(s)
set-source-volume¶
Configure audio source volume.
SOURCE must be the name of a PulseAudio source. VOLUME should be one (applied to all channels) or multiple (one for each channel) floating point values between 0 and 1.
pdtools node set-source-volume [OPTIONS] SOURCE [VOLUME]...
Arguments
-
SOURCE
¶
Required argument
-
VOLUME
¶
Optional argument(s)
start-chute¶
Start a stopped chute.
CHUTE must be the name of a stopped chute.
pdtools node start-chute [OPTIONS] CHUTE
Arguments
-
CHUTE
¶
Required argument
stop-chute¶
Stop a running chute.
CHUTE must be the name of a running chute.
pdtools node stop-chute [OPTIONS] CHUTE
Arguments
-
CHUTE
¶
Required argument
trigger-pdconf¶
Trigger pdconf to reload configuration.
This function is intended for Paradrop daemon developers for debugging purposes. Generally, you should use edit-configuration and edit-chute-configuration for making configuration changes.
pdtools node trigger-pdconf [OPTIONS]
update-chute¶
Install a new version of the chute from the working directory.
Install the files in the current directory as a chute on the node. The directory must contain a paradrop.yaml file. The entire directory will be copied to the node for installation.
pdtools node update-chute [OPTIONS]
Options
-
-d
,
--directory
<directory>
¶ Directory containing chute files
watch-change-logs¶
Stream log messages from an in-progress change.
CHANGE_ID must be the ID of a queued or in-progress change as retrieved from the list-changes command.
pdtools node watch-change-logs [OPTIONS] CHANGE_ID
Arguments
-
CHANGE_ID
¶
Required argument
routers¶
(deprecated) Access router information on the controller.
These commands are deprecated. Please use the equivalent commands under pdtools cloud –help.
pdtools routers [OPTIONS] COMMAND [ARGS]...
claim¶
Claim an existing router.
pdtools routers claim [OPTIONS] TOKEN
Arguments
-
TOKEN
¶
Required argument
create¶
Create a new router.
pdtools routers create [OPTIONS] NAME
Options
-
--orphaned
,
--not-orphaned
¶
-
--claim
<claim>
¶
Arguments
-
NAME
¶
Required argument
store¶
Publish and install from the public chute store.
By default the cloud controller is assumed to be paradrop.org. This can be configured through the environment variable PDSERVER_URL.
It is recommended that you log in with the cloud login command before using the store commands.
pdtools store [OPTIONS] COMMAND [ARGS]...
create-version¶
Push a new version of the chute to the store.
pdtools store create-version [OPTIONS]
describe-chute¶
Show detailed information about a chute in the store.
NAME must be the name of a chute in the store.
pdtools store describe-chute [OPTIONS] NAME
Arguments
-
NAME
¶
Required argument
install-chute¶
Install a chute from the store.
CHUTE must be the name of a chute in the store. NODE must be the name of a node that you control.
pdtools store install-chute [OPTIONS] CHUTE NODE
Options
-
-f
,
--follow
¶
Follow chute updates.
-
-v
,
--version
<version>
¶ Version of the chute to install.
Arguments
-
CHUTE
¶
Required argument
-
NODE
¶
Required argument
list-chutes¶
List chutes in the store that you own or have access to.
pdtools store list-chutes [OPTIONS]
list-versions¶
List versions of a chute in the store.
NAME must be the name of a chute in the store.
pdtools store list-versions [OPTIONS] NAME
Arguments
-
NAME
¶
Required argument
register¶
Register a chute with the store.
The chute information including name will be taken from the paradrop.yaml file in the current working directory. If you receive an error, it may be that a chute with the same name is already registered.
pdtools store register [OPTIONS]
Options
-
--public
,
--not-public
¶
List the chute publicly for other users to download.
watch-update-messages¶
Stream log messages from an in-progress update.
NODE must be the name or ID of a node that you control. UPDATE_ID must be the ID associated with an in-progress update.
pdtools store watch-update-messages [OPTIONS] NODE_ID UPDATE_ID
Options
-
--interval
<interval>
¶ Interval to check for new messages
Arguments
-
NODE_ID
¶
Required argument
-
UPDATE_ID
¶
Required argument