Before You Start

If you've received a Relay hardware development kit and are ready to learn and build and run a workflow, you're in the right place.

Basic Device Operations

First, you'll want to make sure your devices are charged, powered up, activated, and not in do-not-disturb. Below are some basic instructions on using the device.

When powered on and disconnected from the charger, there should be 3 white LEDs on. Give the Assistant (side) button a quick tap and it should say the name of the device and which channel it is on. Because that audio comes from the Relay server, it's a good test of the audio and network connectivity. If it works, you're ready to start!

To see a simple built-in workflow, try speaking the Assistant command "battery" per the documentation above.

Install the CLI

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 to configure them.


Where to Install the CLI

You do not need to install/run the Relay CLI on your workflow server. You can run the Relay CLI on any machine, since all it is doing is updating registration metadata on the Relay server. No workflows are run in the CLI, they are run only on the workflow server via the SDK. You can run the CLI on a machine that is separate from and has no communication with the SDK/workflow server.

Typically the CLI would be installed and run on a local machine that has a web browser, as opposed to a headless server in the cloud, since getting an authorization token for the CLI requires a web browser to access the login page.

The CLI is implemented in Node.js. You should have at least version 16.12.0 of the Node.js runtime installed. You can verify your version of the installed Node.js runtime by running the following command:

node --version

Once the Node.js runtime is installed, you can download the CLI onto your machine by using Node.js' npm utility to run the following command in your shell. The -g flag installs the package globally, so you can use the Relay CLI from any directory on your workstation.

npm install -g @relaypro/cli

If desired, you can look at the CLI source code on github.

Now that the Relay CLI is installed, you can then check the version that it installed, which is a good way to verify it installed successfully:

relay --version

And you should get a result like this:

@relaypro/cli/0.2.5 linux-x64 node-v16.13.2

Log In to the CLI

After installing the CLI, before you use it to register a workflow, you'll need to login with the CLI using your Relay account credentials. This enables you to perform CLI actions within the context of your account.


Relay Account Credentials

Upon order completion of your Relay device, whether a developer's kit or a full production deployment, you should have received the login credentials for your Relay account. These are the same login credentials used for accessing Dash. If you don't have the login credentials or have lost them, please contact Relay Support.

Enter the command relay login into your shell. You should be taken to a separate web browser that prompts you to login. In addition to your Relay account email id and password, click the "Remember me" button, enter the captcha, and press "Sign In".

relay login

Upon successful login, the web browser should say:
Relay CLI authorization complete. You can close this tab.
And the CLI should say:

Waiting for login... done
Logged in

To verify you are successfully logged in, run the relay whoami command, which will query the Relay server for information about your Relay account, and the output should look like this:

$ relay whoami
=== You are

Name:               Alice Customer
Email:              [email protected]
Auth User ID:       98071da3-572b-4552-be88-8907a9ad0123
Relay User ID:      VIRT1cMBYVBIPZ3kR7aoIsIlat
Default Subscriber: ee4547e0-aaef-4956-b853-ade0ba436c78

You could also run the relay devices command, which will query the Relay server for all the devices on your Relay account, and the output should look like this:

$ relay devices

Now your Relay CLI is set up and ready to go!