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

Using the CLI

Install and Login

Using the Help Command

Popular Workflow Commands

📘
Long and Short arguments

Install

List and Delete

Filtering and Sorting

📘
Full details of workflow list

Scripting the CLI

Install and Login

Using the Help Command

Popular Workflow Commands

📘Long and Short arguments

Install

List and Delete

Filtering and Sorting

📘Full details of workflow list

Scripting the CLI

📘
Long and Short arguments

📘
Full details of workflow list