The VuePilot CLI allows you to programmatically control your VuePilot players and the content displayed on your screens using a terminal or automated process.
Trigger apps, notifications and send remote commands to your VuePilot controlled screens from the command line using scripts or shell commands triggered by build pipelines, system events or other automated processes.
The VuePilot CLI unlocks a powerful set of automation tools that can be used to automate and control content on your screens without the need to manually interact with the VuePilot
Use Cases
- Deployment pipeline progress notifications
- Automated app configuration updates (update URLs, content, images and video etc)
- Automated synchronisation of screen rotations (start, stop on schedule)
- Automated notifications for information and alarms displayed on screens
Installation
- Download the version for your operating system at https://www.vuepilot.com/cli
- Extract the contents of the package and move the executable to a location on your system of your choice
- sudo cp ./vuepilot /usr/local/bin/vuepilot – on linux systems for example for the binary to be available in your $PATH
- We will assume vuepilot is within your $PATH for the following steps, if not ensure you run with relative path ie ./vuepilot
- Open a terminal / command line and run vuepilot to test.
Setup Credentials
The VuePilot CLI requires that your API key is available in your shell environment. This must be available within the VUEPILOT_API_KEY environment variable
Your API key can be found on your profile page from the dashboard – https://www.vuepilot.com/users/edit
Linux / Mac OS
- Open your ~/.zshrc or ~/.bash_profile for editing
- Add the line export VUEPILOT_API_KEY=<your api key>
- Save the file and reload your shell environment
Windows
Follow the instructions from the following article to add the VUEPILOT_API_KEY environment variable to your system
How to set the path and environment variables in Windows
https://www.computerhope.com/issues/ch000549.htm
Usage
Once you have installed the tool and setup your credentials you are ready to use the CLI. The CLI follows standard command line argument conventions which will be familiar to you if you have ever used a tool like the aws CLI or kubectl
Type vuepilot to see a listing of available commands. The commands app , rotation , machine etc allow you to interact with these resources from the VuePilot API.
Type the name of the command and hit enter to see any available sub commands.
For example: Type vuepilot machineto see available sub commands for the machine command.
You can then append these sub commands. ie vuepilot machine list to list your machines
With any command you can pass the option -h or –help to see the help instructions and available options for that particular command or sub command.
Output Formats – JSON vs List
Some commands offer an output option (-o or –output) this will allow you to either print the results to screen in a human readable list or as JSON which can be used to integrate into other systems.
Outputting as JSON will also display additional attributes that are not shown in the standard list view. The standard list contains the most common attributes you would want to see.
As an example
- vuepilot machine list lists out your machines in a human readable format
- vuepilot machine list -o json
JSON outputs can be piped into command line JSON parsing tools such as JQ which can then be queried directly creating a very powerful set of command line tools.
JQ Example
To get a listing of all machine names in your account, using JSON output and JQ:
vuepilot machine list -o json | jq “.[] | .name”
Notifications
Notifications are a powerful tool for triggering alarms and information messages for a brief period of time on screens in your business. You can integrate these notifications into your backend processes and build pipelines to show information on screens in your business triggered by automated processes.
There are 4 types of notifications, each with a different colour and image, these are success, warning, info and alarm
A custom image can also be provided instead of the default notification images using the –url option.
You can specify how long you want the notification to by passing in the number of seconds to the command with the -s option.
Example Notify Commands
Notify Machines 8726 & 8847 Success Message “Application Deployed” For 30 Seconds
vuepilot machine notify -m 8726,8847 -t "Application Deployed" -d "The application has been successfully deployed" -c success -s 30
Notify Machines 8726 & 8847 Alarm Message “Application Failed” For 60 Seconds
vuepilot machine notify -m 8726,8847 -t "Application Failed" -d "The application has failed" -c alarm -s 60