Screenly CLI

The Screenly CLI simplifies interactions with Screenly through your terminal, designed for both manual use and task automation.

Installation

From Releases

Download the latest release here.

Homebrew (macOS only)

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

Nix

$ nix-shell -p screenly-cli

Docker

For other operating systems or Docker usage:

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

Building from Source

To build the Screenly CLI from source, ensure you have Rust installed:

$ cargo build --release

The screenly binary will be located in target/release.

To configure a non-production API server, set the API_SERVER_NAME environment variable:

$ API_SERVER_NAME=local cargo build --release

GitHub Action

Integrate Screenly CLI into your GitHub workflows:

Inputs

screenly_api_token

Required Screenly API token for your team.

cli_commands

Required Command to execute (e.g., screen list).

cli_version

Optional CLI version override.

Example usage

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

Commands

Command line interface is intended for quick interaction with Screenly through terminal. Moreover, this CLI is built such that it can be used for automating tasks.

Usage: screenly [OPTIONS] <COMMAND>

screenly [OPTIONS] <COMMAND>

Subcommands:

• login — Logins with the token and stores it for further use if it's valid. You can set API_TOKEN environment variable to override used API token
• logout — Logouts and removes stored token
• screen — Screen related commands
• asset — Asset related commands
• playlist — Playlist related commands
• edge-app — Edge App related commands

Options:

• -j, --json — Enables JSON output

Login

Logins with the token and stores it for further use if it's valid. You can set API_TOKEN environment variable to override used API token

Usage: screenly login

screenly login

Logout

Logouts and removes stored token

Usage: screenly logout

screenly logout

Screen

Screen related commands

Usage: screenly screen <COMMAND>

screenly screen <COMMAND>

Subcommands:

• list — Lists your screens
• get — Gets a single screen by id
• add — Adds a new screen
• delete — Deletes a screen. This cannot be undone

List

Lists your screens

Usage: screenly screen list [OPTIONS]

screenly screen list [OPTIONS]

Options:

• -j, --json — Enables JSON output

Get

Gets a single screen by id

Usage: screenly screen get [OPTIONS] <UUID>

screenly screen get [OPTIONS] <UUID>

Arguments:

• <UUID> — UUID of the screen

Options:

• -j, --json — Enables JSON output

Add

Adds a new screen

Usage: screenly screen add [OPTIONS] <PIN> [NAME]

screenly screen add [OPTIONS] <PIN> [NAME]

Arguments:

• <PIN> — Pin code created with registrations endpoint
• <NAME> — Optional name of the new screen

Options:

• -j, --json — Enables JSON output

Delete

Deletes a screen. This cannot be undone

Usage: screenly screen delete <UUID>

screenly screen delete <UUID>

Arguments:

• <UUID> — UUID of the screen to be deleted

Asset

Asset related commands

Usage: screenly asset <COMMAND>

screenly asset <COMMAND>

Subcommands:

• list — Lists your assets
• get — Gets a single asset by id
• add — Adds a new asset
• delete — Deletes an asset. This cannot be undone
• inject-js — Injects JavaScript code inside of the web asset. It will be executed once the asset loads during playback
• set-headers — Sets HTTP headers for web asset
• update-headers — Updates HTTP headers for web asset
• basic-auth — Shortcut for setting up basic authentication headers
• bearer-auth — Shortcut for setting up bearer authentication headers

List

Lists your assets

Usage: screenly asset list [OPTIONS]

screenly asset list [OPTIONS]

Options:

• -j, --json — Enables JSON output

Get

Gets a single asset by id

Usage: screenly asset get [OPTIONS] <UUID>

screenly asset get [OPTIONS] <UUID>

Arguments:

• <UUID> — UUID of the asset

Options:

• -j, --json — Enables JSON output

Add

Adds a new asset

Usage: screenly asset add [OPTIONS] <PATH> <TITLE>

screenly asset add [OPTIONS] <PATH> <TITLE>

Arguments:

• <PATH> — Path to local file or URL for remote file
• <TITLE> — Asset title

Options:

• -j, --json — Enables JSON output

Delete

Deletes an asset. This cannot be undone

Usage: screenly asset delete <UUID>

screenly asset delete <UUID>

Arguments:

• <UUID> — UUID of the asset to be deleted

Inject js

Injects JavaScript code inside of the web asset. It will be executed once the asset loads during playback

Usage: screenly asset inject-js <UUID> <PATH>

screenly asset inject-js <UUID> <PATH>

Arguments:

• <UUID> — UUID of the web asset to inject with JavaScript
• <PATH> — Path to local file or URL for remote file

Set headers

Sets HTTP headers for web asset

Usage: screenly asset set-headers <UUID> <HEADERS>

screenly asset set-headers <UUID> <HEADERS>

Arguments:

• <UUID> — UUID of the web asset to set http headers
• <HEADERS> — HTTP headers in the following form header1=value1[,header2=value2[,...]]. This command replaces all headers of the asset with the given headers (when an empty string is given, e.g. --set-headers "", all existing headers are removed, if any)

Update headers

Updates HTTP headers for web asset

Usage: screenly asset update-headers <UUID> <HEADERS>

screenly asset update-headers <UUID> <HEADERS>

Arguments:

• <UUID> — UUID of the web asset to set http headers
• <HEADERS> — HTTP headers in the following form header1=value1[,header2=value2[,...]]. This command updates only the given headers (adding them if new), leaving any other headers unchanged

Basic auth

Shortcut for setting up basic authentication headers

Usage: screenly asset basic-auth <UUID> <CREDENTIALS>

screenly asset basic-auth <UUID> <CREDENTIALS>

Arguments:

• <UUID> — UUID of the web asset to set up basic authentication for
• <CREDENTIALS> — Basic authentication credentials in "user=password" form

Bearer auth

Shortcut for setting up bearer authentication headers

Usage: screenly asset bearer-auth <UUID> <TOKEN>

screenly asset bearer-auth <UUID> <TOKEN>

Arguments:

• <UUID> — UUID of the web asset to set up basic authentication for
• <TOKEN> — Bearer token

Playlist

Playlist related commands

Usage: screenly playlist <COMMAND>

screenly playlist <COMMAND>

Subcommands:

• create — Creates a new playlist
• list — Lists your playlists
• get — Gets a single playlist by id
• delete — Deletes a playlist. This cannot be undone
• append — Adds an asset to the end of the playlist
• prepend — Adds an asset to the beginning of the playlist
• update — Patches a given playlist

Create

Creates a new playlist

Usage: screenly playlist create [OPTIONS] <TITLE> [PREDICATE]

screenly playlist create [OPTIONS] <TITLE> [PREDICATE]

Arguments:

• <TITLE> — Title of the new playlist
• <PREDICATE> — Predicate for the new playlist. If not specified it will be set to "TRUE"

Options:

• -j, --json — Enables JSON output

List

Lists your playlists

Usage: screenly playlist list [OPTIONS]

screenly playlist list [OPTIONS]

Options:

• -j, --json — Enables JSON output

Get

Gets a single playlist by id

Usage: screenly playlist get <UUID>

screenly playlist get <UUID>

Arguments:

• <UUID> — UUID of the playlist

Delete

Deletes a playlist. This cannot be undone

Usage: screenly playlist delete <UUID>

screenly playlist delete <UUID>

Arguments:

• <UUID> — UUID of the playlist to be deleted

Append

Adds an asset to the end of the playlist

Usage: screenly playlist append [OPTIONS] <UUID> <ASSET_UUID> [DURATION]

screenly playlist append [OPTIONS] <UUID> <ASSET_UUID> [DURATION]

Arguments:

• <UUID> — UUID of the playlist
• <ASSET_UUID> — UUID of the asset
• <DURATION> — Duration of the playlist item in seconds. If not specified it will be set to 15 seconds

Options:

• -j, --json — Enables JSON output

Prepend

Adds an asset to the beginning of the playlist

Usage: screenly playlist prepend [OPTIONS] <UUID> <ASSET_UUID> [DURATION]

screenly playlist prepend [OPTIONS] <UUID> <ASSET_UUID> [DURATION]

Arguments:

• <UUID> — UUID of the playlist
• <ASSET_UUID> — UUID of the asset
• <DURATION> — Duration of the playlist item in seconds. If not specified it will be set to 15 seconds

Options:

• -j, --json — Enables JSON output

Update

Patches a given playlist

Usage: screenly playlist update

screenly playlist update

Edge app

Edge App related commands

Usage: screenly edge-app <COMMAND>

screenly edge-app <COMMAND>

Subcommands:

• create — Creates Edge App in the store
• list — Lists your Edge Apps
• rename — Renames Edge App
• run — Runs Edge App emulator
• setting — Settings commands
• instance — Instance commands
• deploy — Deploys assets and settings of the Edge App and release it
• delete — Deletes an Edge App. This cannot be undone
• validate — Validates Edge App manifest file

Create

Creates Edge App in the store

Usage: screenly edge-app create [OPTIONS] --name <NAME>

screenly edge-app create [OPTIONS] --name <NAME>

Options:

• -n, --name <NAME> — Edge App name
• -p, --path <PATH> — Path to the directory with the manifest. If not specified CLI will use the current working directory
• -i, --in-place — Use an existing Edge App directory with the manifest and index.html

List

Lists your Edge Apps

Usage: screenly edge-app list [OPTIONS]

screenly edge-app list [OPTIONS]

Options:

• -j, --json — Enables JSON output

Rename

Renames Edge App

Usage: screenly edge-app rename [OPTIONS] --name <NAME>

screenly edge-app rename [OPTIONS] --name <NAME>

Options:

• -p, --path <PATH> — Path to the directory with the manifest. If not specified CLI will use the current working directory
• -n, --name <NAME> — Edge App name

Run

Runs Edge App emulator

Usage: screenly edge-app run [OPTIONS]

screenly edge-app run [OPTIONS]

Options:

• -p, --path <PATH> — Path to the directory with the manifest. If not specified CLI will use the current working directory
• -s, --secrets <SECRETS>
• -g, --generate-mock-data — Generates mock data to be used with Edge App run

Setting

Settings commands

Usage: screenly edge-app setting <COMMAND>

screenly edge-app setting <COMMAND>

Subcommands:

• list — Lists Edge App settings
• set — Sets Edge App setting

List

Lists Edge App settings

Usage: screenly edge-app setting list [OPTIONS]

screenly edge-app setting list [OPTIONS]

Options:

• -p, --path <PATH> — Path to the directory with the manifest. If not specified CLI will use the current working directory
• -j, --json — Enables JSON output

Set

Sets Edge App setting

Usage: screenly edge-app setting set [OPTIONS] <SETTING_PAIR>

screenly edge-app setting set [OPTIONS] <SETTING_PAIR>

Arguments:

• <SETTING_PAIR> — Key value pair of the setting to be set in the form of key=value

Options:

• -p, --path <PATH> — Path to the directory with the manifest. If not specified CLI will use the current working directory

Instance

Instance commands

Usage: screenly edge-app instance <COMMAND>

screenly edge-app instance <COMMAND>

Subcommands:

• list — Lists Edge App instances
• create — Creates Edge App instance
• delete — Deletes Edge App instance
• update — Update Edge App instance based on changes in the instance.yml

List

Lists Edge App instances

Usage: screenly edge-app instance list [OPTIONS]

screenly edge-app instance list [OPTIONS]

Options:

• -p, --path <PATH> — Path to the directory with the manifest. If not specified CLI will use the current working directory
• -j, --json — Enables JSON output

Create

Creates Edge App instance

Usage: screenly edge-app instance create [OPTIONS]

screenly edge-app instance create [OPTIONS]

Options:

• -n, --name <NAME> — Name of the Edge App instance
• -p, --path <PATH> — Path to the directory with the manifest. If not specified CLI will use the current working directory

Delete

Deletes Edge App instance

Usage: screenly edge-app instance delete [OPTIONS]

screenly edge-app instance delete [OPTIONS]

Options:

• -p, --path <PATH> — Path to the directory with the manifest. If not specified CLI will use the current working directory

Update

Update Edge App instance based on changes in the instance.yml

Usage: screenly edge-app instance update [OPTIONS]

screenly edge-app instance update [OPTIONS]

Options:

• -p, --path <PATH> — Path to the directory with the manifest. If not specified CLI will use the current working directory

Deploy

Deploys assets and settings of the Edge App and release it

Usage: screenly edge-app deploy [OPTIONS]

screenly edge-app deploy [OPTIONS]

Options:

• -p, --path <PATH> — Path to the directory with the manifest. If not specified CLI will use the current working directory
• -d, --delete-missing-settings <DELETE_MISSING_SETTINGS>

Possible values: true, false

Delete

Deletes an Edge App. This cannot be undone

Usage: screenly edge-app delete [OPTIONS]

screenly edge-app delete [OPTIONS]

Options:

• -p, --path <PATH> — Path to the directory with the manifest. If not specified CLI will use the current working directory

Validate

Validates Edge App manifest file

Usage: screenly edge-app validate [OPTIONS]

screenly edge-app validate [OPTIONS]

Options:

• -p, --path <PATH> — Path to the directory with the manifest. If not specified CLI will use the current working directory