NAV
shell

Command-Line Interface (CLI)

Screenly's CLI is designed to provide developers with a more streamlined and efficient means of interfacing with our platform. In addition, it stands as a comprehensive reference implementation for our API. Fully open-sourced, it underscores our commitment to transparency and community collaboration.

Installation

Releases are built automatically. You can download the latest release here.

On macOS you can also use Homebrew to install the latest version.

$ brew tap screenly/screenly-cli
$ brew install screenly-cli

For other operating systems, you can either use the pre-compiled binaries, or use our Docker wrapper:

$ docker run --rm \
    -e API_TOKEN=YOUR_API_TOKEN \
    screenly/cli:latest \
    help
[...]

Pro-tip: You can append --json to most commands, which will not only provide you with an output that can be piped to say jq, but will also provide more information than the regular ASCII formatted output.

Logging In

In order to use the CLI, you first need to login. It is worth noting that the API token that you are using to login is tied to a particular team.

Logging into Screenly

$ screenly login

If you want to interact with multiple teams, you can generate your API tokens and provide them using the API_TOKEN environment variable.

Assets

You can:

Add a web asset:

$ screenly asset add https://news.ycombinator.com "Hacker News"
+----------------------------+-------------+------+--------+
| Id                         | Title       | Type | Status |
+----------------------------+-------------+------+--------+
| XXXXXXXXXXXXXXXXXXXXXXXXX  | Hacker News | N/A  | none   |
+----------------------------+-------------+------+--------+

You can also use the --json feature, which is handy in conjunction with jq for getting say the Asset ID of a particular asset:

$ screenly asset list --json | \
    jq -r '.[] | select (.title|test("Hacker News")) | .id'
XXXXXXXXXXXXXXXXXXXXXXXXXX

Inject JavaScript to a website

$ export JAVASCRIPT_URL='https://raw.githubusercontent.com/Screenly/playground/master/javascript-injectors/examples/yahoo-cookies-consent-closing.js'
$ screenly asset inject-js "$ASSET_ID" "$JAVASCRIPT_URL"
20XX-XX-XXTXX:XX:XX.XXXZ INFO  [screenly] Asset updated successfully.

Screens

You can:

Listing screens:

$ screenly screen list
+----------------------------+-----------------------+-----------------------+---------+---------------------------------+-------------------+
| Id                         | Name                  | Hardware Version      | In Sync | Last Ping                       | Uptime            |
+----------------------------+-----------------------+-----------------------+---------+---------------------------------+-------------------+
| XXXXXXXXXXXXXXXXXXXXXXXXXX | Lobby Screen          | Screenly Player Max   |   ✅    | 2023-01-22T09:56:23.89686+00:00 | 8days 23h 18m 53s |
+----------------------------+-----------------------+-----------------------+---------+---------------------------------+-------------------+
| XXXXXXXXXXXXXXXXXXXXXXXXXX | Grafana Dashboard     | Raspberry Pi 3B+      |   ✅    | 2023-01-22T09:54:17.88319+00:00 | 10days 22h 9m 32s |
+----------------------------+-----------------------+-----------------------+---------+---------------------------------+-------------------+

Playlists

You can:

List all your playlists

$ screenly playlist list
+----------------------------+------------------------+
| Id                         | Title                  |
+----------------------------+------------------------+
| 01GBQ0E5JW7P6C2XXXXXXXXXXX | Test Playlist          |
+----------------------------+------------------------+
| 01C8G4Z24G0005XXXXXXXXXXXX | Another Test           |
+----------------------------+------------------------+
| 01D36GG9MG0005XXXXXXXXXXXX | Some Images            |
+----------------------------+------------------------+

List

This will return all of your playlists, along with the Playlist ID (first column). The Playlist ID is what you will be using below as the argument for most playlist operations.

Delete

Delete a playlist

$ screenly playlist delete $PLAYLIST_ID

Delete simply deletes the specified playlist.

Get / Update

Download a playlist

$ screenly playlist get $PLAYLIST_ID
{
  "predicate": "TRUE AND ($DATE >= 1520899200000)",
  "playlist_id": "01C8G4Z24G0005BCXXXXXXXXXX",
  "items": [
    {
      "asset_id": "01C8G5Q8HR0001GNXXXXXXXXXX",
      "duration": 15
    },
    {
      "asset_id": "01C8G5Q8HR000DHXXXXXXXXXXX",
      "duration": 60
    },
    {
      "asset_id": "01C8G4GGA8000XXXXXXXXXXXXX",
      "duration": 15
    },
    {
      "asset_id": "01C8JCEW38000XXXXXXXXXXXXX",
      "duration": 60
    }
  ]
}

Update a playlist

$ cat playlist.json | screenly playlist update

The playlist get syntax downloads the playlist. This is handy for editing a playlist. This command is designed to be compatible with UNIX pipes, such that you can take this input and pipe it into other commands, such as playlist update.

For instance, we could use a simple sed filter to replace the an asset in a playlist with screenly playlist get $PLAYLIST_ID | sed 's/ASSET_ID_1/ASSET_ID_2/g' | jq | screenly playlist update. Note that we're using jq here in the pipeline just to ensure the JSON is valid before sending it off to the update command.

Another important thing to note about the playlist update command is that it doesn't require you to pass on the $PLAYLIST_ID, since it is already part of the payload.

Append / Prepend

Add an asset to the end of a playlist

$ screenly playlist append $PLAYLIST_ID $ASSET_ID [$DURATION]

Add an asset to the beginning of a playlist

$ screenly playlist prepend $PLAYLIST_ID $ASSET_ID [$DURATION]

The commands append and prepend are really just shorthands for quickly adding an asset to a playlist. They're both rather self explanatory. append adds the given asset to the end of the playlist, whereas prepend adds it as the first asset.

Both command accepts an optional argument for duration (in seconds). If unspecified, the default value is 15s.

Create

This command can create an empty playlist stanza.

Edge Apps

For details on screenly edge-apps [...], see the Edge App page.

CI/CD in GitHub Actions

Our CLI is also available as a GitHub Action workflow. It would however be very trivial to use the CLI in other CI/CD tools, like Jenkins, Travis or similar.

Inputs

screenly_api_token

Required: The Screenly API token for your team. You can retrieve this by going to Settings -> Team -> Tokens. Note that API tokens are limited in scope to your team.

You should use a GitHub Action Secret to store this rather than hard coding this in your code base.

cli_commands

Required: This is the command you want to pass on, such as screen list.

cli_version

Use this option to override the CLI version used by the Action. Must point to a valid release.

Example usage

uses: screenly/cli@master
with:
  screenly_api_token: ${{ secrets.SCREENLY_API_TOKEN }}
  cli_commands: screen list
shell