Using the CLI
Install and Login
The Relay CLI (Command Line Interface) is the tool that you will use to register and manage your workflows. To do anything with Relay workflows, you'll need to use the CLI. If you haven't already, follow the instructions to install and login to the CLI.
Using the Help Command
To see the different commands that you can do on the Relay CLI, try typing in relay help
into the shell. You should get something like this:
$ relay help
Relay developer CLI
VERSION
@relaypro/cli/0.2.6 linux-x64 node-v17.9.0
USAGE
$ relay [COMMAND]
TOPICS
audio List custom audio
subscriber show default subscriber
token generate a token that can be used with the Relay SDK
workflow Manage workflow configurations
COMMANDS
devices list all device ids
env displays the configured environment
help Display help for relay.
login login with your Relay credentials
logout logout and forget any tokens
update update the relay CLI
version
whoami display the current logged in user
This lists out information about the version of the CLI that you have installed on your machine, how to use the CLI under the USAGE section, and the different topics and commands you can use on the CLI under TOPICS and COMMANDS. Items listed under TOPICS means that it is a grouping that has additional commands under it, such as when "workflow" is a TOPIC, there are the commands workflow create
, workflow list
, etc, and doing a relay help workflow
will show you those commands.
Perhaps you want to see all of the devices on your account. You can use the relay devices
command, and you will see the device IDs that are registered with your account.
You can also use the relay whoami
command to verify that you are properly logged in to your account, to have a valid context for running CLI commands.
Under each of the commands in the TOPICS section, you can see even more commands that you can use in the CLI. For example, if you use the relay workflow
command, you will see the following:
$ relay help workflow
Manage workflow configurations
USAGE
$ relay workflow:COMMAND
TOPICS
workflow args List a workflow's args
workflow create Create or update a workflow triggered by crossing a charging or discharging threshold of any device on the account
COMMANDS
workflow args List a workflow's args
workflow delete Destructively delete and remove a workflow
workflow install Install an existing workflow into one or more devices
workflow list List workflow configurations
workflow uninstall Uninstall an existing workflow from one or more devices
For any CLI command you'd like to get help with, you can prefix the command with the word help
, or you can end with the --help
argument:
$ relay help workflow create phrase
$ relay workflow create phrase --help
You may consider running the following commands to get an idea of the capabilities in the CLI:
$ relay help
Relay developer CLI
VERSION
@relaypro/cli/0.2.5 linux-x64 node-v16.13.2
USAGE
$ relay [COMMAND]
TOPICS
audio List custom audio
subscriber show default subscriber
token generate a token that can be used with the Relay SDK
workflow Manage workflow configurations
COMMANDS
devices list all device ids
env displays the configured environment
help Display help for relay.
login login with your Relay credentials
logout logout and forget any tokens
update update the relay CLI
version
whoami display the current logged in user
$ relay help workflow
Manage workflow configurations
USAGE
$ relay workflow COMMAND
TOPICS
workflow args List a workflow's args
workflow create Create or update a workflow triggered by crossing a charging or discharging threshold of any device on the account
COMMANDS
workflow args List a workflow's args
workflow delete Destructively delete and remove a workflow
workflow install Install an existing workflow into one or more devices
workflow list List workflow configurations
workflow uninstall Uninstall an existing workflow from one or more devices
$ relay help subscriber
show default subscriber
USAGE
$ relay subscriber COMMAND
COMMANDS
subscriber get show default subscriber
subscriber list list subscribers
subscriber refresh refresh available subscribers
subscriber set set the default subscriber
$ relay help token
generate a token that can be used with the Relay SDK
USAGE
$ relay token COMMAND
COMMANDS
token generate generate a token that can be used with the Relay SDK
$ relay help audio
List custom audio
USAGE
$ relay audio COMMAND
COMMANDS
audio create List custom audio
audio delete List custom audio
audio list List custom audio
Popular Workflow Commands
Long and Short arguments
The CLI has a short alias for each long argument. For example
-u
versus--uri
. Throughout this documentation we'll use the long name for the CLI arguments, since it is easier to read. Feel free to use the short names for the CLI arguments as soon as you are comfortable.
Install
If you want to change the devices upon which a workflow is installed, you can re-run the install
CLI command and it will overwrite the previous installation list. The following sequence will result with the workflow being installed on just one device even though we initially install it to all devices:
$ relay workflow:install --workflow-id wf_hello_Xrl0Uab4dymD6C9CxExkeeD --install-all
$ relay workflow:install --workflow-id wf_hello_Xrl0Uab4dymD6C9CxExkeeD --install 990007560023456
List and Delete
If you ever want to delete a workflow that you have installed, you can use the delete
CLI command. With this command, you will need to provide the ID of the workflow that you would like to delete. To find the IDs of all of the workflows that you have installed under your account, you can use the list
command. The following sequence lists out all of the workflows registered on a device, and then removes the first one.
$ relay workflow list
=== Installed Workflows
ID Name Type
────────────────────────────────────── ─────────── ─────────────
wf_variables_dkeudklsle938dFjdkdlFKDJ panic button:single
wf_helloworld_9djekKDJldkdje93dkjKDKJd hello_world phrases:hello
$ relay workflow delete -w wf_variables_dkeudklsle938dFjdkdlFKDJ
$ relay workflow list
=== Installed Workflows
ID Name Type
────────────────────────────────────── ─────────── ─────────────
wf_helloworld_9djekKDJldkdje93dkjKDKJd hello_world phrases:hello
Filtering and Sorting
If you want to organize the output of a CLI command, you can use some of the filtering and sorting flags that are available in the CLI. For example, if you want to sort the output of relay workflow list
to be in ascending order by name, you can enter relay workflow list --sort=Name
.
$ relay workflow list
=== Installed Workflows
ID Name Type
────────────────────────────────────── ─────────── ─────────────
wf_variables_dkeudklsle938dFjdkdlFKDJ panic button:single
wf_helloworld_9djekKDJldkdje93dkjKDKJd hello_world phrases:hello
$ relay workflow list --sort=Name
=== Installed Workflows
ID Name Type
────────────────────────────────────── ─────────── ─────────────
wf_helloworld_9djekKDJldkdje93dkjKDKJd hello_world phrases:hello
wf_variables_dkeudklsle938dFjdkdlFKDJ panic button:single
In addition to this, there are a few other helpful flags for organizing the table output. A common use case for these flags would be for organizing your analytical data retrieved from the relay workflow analytics
command. To see more on filtering, sorting, and organizing the output of your data, see the Using Analytics section.
Full details of workflow list
By default when listing the existing workflows that are registered, it will not show the URL of the workflow server, the list of devices the workflow is installed on, or the arguments that the trigger will pass to the workflow. To see those use the -x option:
relay workflow list -x
Scripting the CLI
If you would like to parse the output of the CLI commands but need that output to be structured so you can accurately parse it, there is a way to do that. There is a global command-line argument --json
(can be used on all CLI commands) that will format the output as JSON. The structure will be unique for each CLI command, as the output for each command is typically unique.
Here is probably the simplest example, the relay version
command:
$ relay version --json
{
"cliVersion": "@relaypro/cli/1.4.0",
"architecture": "linux-x64",
"nodeVersion": "node-v16.13.2"
}
$ relay version
@relaypro/cli/1.3.2 linux-x64 node-v16.13.2
$
This JSON output can be combined with a parsing tool such as jq
to pull out individual fields, as shown in this example:
$ relay whoami
=== You are
Name: Alice Smith
Email: [email protected]
Default Subscriber: ee4547e0-aaef-4956-b853-ade0ba345678
Auth User ID: 98071da3-572b-4552-be88-8907a9abcdef
Relay User ID: VIRT1cMBYVBIPZ3kR7aojmYRel
Capabilities: workflow_sdk: true, indoor_positioning: true, ui_nfc: true, calling: true, calling_between_devices_support: true, enable_audit_logs: true
$ relay whoami --json
{
"Name": "Alice Smith",
"Email": "[email protected]",
"Auth User ID": "98071da3-572b-4552-be88-8907a9abcdef",
"Relay User ID": "VIRT1cMBYVBIPZ3kR7aojmYRel",
"Default Subscriber": "ee4547e0-aaef-4956-b853-ade0ba345678",
"Capabilities": {
"workflow_sdk": true,
"indoor_positioning": true,
"ui_nfc": true,
"calling": true,
"calling_between_devices_support": true,
"enable_audit_logs": true
}
}
$ relay whoami --json | jq .Capabilities.workflow_sdk
true
Updated about 1 year ago