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

[!NOTE] If you're building from source in Ubuntu, make sure to install build-essential: bash sudo apt-get install -y build-essential

Otherwise, you'll get the following error: error: linker `cc` not found

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 — Logs in with the provided token and stores it for further use if valid. You can set the API_TOKEN environment variable to override the stored token
logout — Logs out and removes the stored token
screen — Screen related commands
asset — Asset related commands
playlist — Playlist related commands
edge-app — Edge App related commands
mcp — Starts the MCP (Model Context Protocol) server on stdio for AI assistant integration

Options:

-j, --json — Enables JSON output

Logs in with the provided token and stores it for further use if valid. You can set the API_TOKEN environment variable to override the stored token

Usage: screenly login

screenly login

Logout

Logs out and removes the 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 a web asset
update-headers — Updates HTTP headers for a web asset
basic-auth — Sets up basic authentication headers for a web asset
bearer-auth — Sets up bearer authentication headers for a web asset

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 a web asset

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

screenly asset set-headers <UUID> <HEADERS>

Arguments:

<UUID> — UUID of the web asset
<HEADERS> — HTTP headers in the form header1=value1[,header2=value2[,...]]. This command replaces all headers of the asset with the given headers. Use an empty string (e.g., --set-headers "") to remove all existing headers

Update headers

Updates HTTP headers for a web asset

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

screenly asset update-headers <UUID> <HEADERS>

Arguments:

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

Basic auth

Sets up basic authentication headers for a web asset

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

screenly asset basic-auth <UUID> <CREDENTIALS>

Arguments:

<UUID> — UUID of the web asset
<CREDENTIALS> — Basic authentication credentials in "user=password" form

Bearer auth

Sets up bearer authentication headers for a web asset

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

screenly asset bearer-auth <UUID> <TOKEN>

Arguments:

<UUID> — UUID of the web asset
<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 — Updates a playlist from JSON input on stdin

Create

Creates a new playlist.

Playlists use a predicate DSL to control when they are shown. The predicate is a boolean expression using these variables:

$DATE - Current date as Unix timestamp in milliseconds $TIME - Time of day in ms since midnight (0-86400000) $WEEKDAY - Day of week (0=Sun, 1=Mon, ..., 6=Sat)

Operators: =, <=, >=, <, >, AND, OR, NOT Special: BETWEEN {min, max}, IN {val1, val2, ...}

Time reference (ms): 32400000=9AM, 43200000=12PM, 61200000=5PM

Examples: TRUE - Always show $WEEKDAY IN {1, 2, 3, 4, 5} - Weekdays only $TIME BETWEEN {32400000, 61200000} - 9 AM to 5 PM NOT $WEEKDAY IN {0, 6} - Exclude weekends

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

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

Arguments:

<TITLE> — Title of the new playlist
<PREDICATE> — Predicate expression controlling when the playlist is shown.

Variables: $DATE - Unix timestamp in milliseconds $TIME - Milliseconds since midnight (0-86400000) $WEEKDAY - Day of week (0=Sun, 1=Mon, ..., 6=Sat)

Operators: =, <=, >=, <, >, AND, OR, NOT Special: BETWEEN {min, max}, IN {val1, val2, ...}

Time reference: 32400000=9AM, 43200000=12PM, 61200000=5PM, 72000000=8PM

Examples: TRUE - Always show $WEEKDAY IN {1, 2, 3, 4, 5} - Weekdays only $TIME BETWEEN {32400000, 61200000} - 9 AM to 5 PM NOT $WEEKDAY IN {0, 6} - Exclude weekends

Default: 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. Defaults 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. Defaults to 15 seconds

Options:

-j, --json — Enables JSON output

Update

Updates a playlist from JSON input on stdin

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 an Edge App in the store
list — Lists your Edge Apps
rename — Renames an Edge App
run — Runs the Edge App emulator
setting — Edge App setting commands
instance — Edge App instance commands
deploy — Deploys assets and settings of the Edge App and releases it
delete — Deletes an Edge App. This cannot be undone
validate — Validates the Edge App manifest file

Create

Creates an 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. Defaults to the current working directory
-i, --in-place — Use an existing Edge App directory with the manifest and index.html
-e, --entrypoint <ENTRYPOINT> — Remote entrypoint URL. When set, the created app uses entrypoint.type = remote-global with this URL and a starter screenly_inject.js is dropped next to screenly.yml. The inject file is shipped with each deploy and the player runs it on every load

List

Lists your Edge Apps

Usage: screenly edge-app list [OPTIONS]

screenly edge-app list [OPTIONS]

Options:

-j, --json — Enables JSON output

Rename

Renames an 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. Defaults to the current working directory
-n, --name <NAME> — New name for the Edge App

Run

Runs the 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. Defaults to the current working directory
-s, --secrets <SECRETS> — Secrets to pass to the Edge App in the form KEY=VALUE. Can be specified multiple times
-g, --generate-mock-data — Generates mock data for use with the Edge App emulator

Setting

Edge App setting commands

Usage: screenly edge-app setting <COMMAND>

screenly edge-app setting <COMMAND>

Subcommands:

list — Lists Edge App settings
set — Sets an 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. Defaults to the current working directory
-j, --json — Enables JSON output

Set

Sets an 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 in the form key=value

Options:

-p, --path <PATH> — Path to the directory with the manifest. Defaults to the current working directory

Instance

Edge App instance commands

Usage: screenly edge-app instance <COMMAND>

screenly edge-app instance <COMMAND>

Subcommands:

list — Lists Edge App instances
create — Creates an Edge App instance
delete — Deletes an Edge App instance
update — Updates an Edge App instance based on changes in 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. Defaults to the current working directory
-j, --json — Enables JSON output

Create

Creates an 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. Defaults to the current working directory

Delete

Deletes an 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. Defaults to the current working directory

Update

Updates an Edge App instance based on changes in 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. Defaults to the current working directory

Deploy

Deploys assets and settings of the Edge App and releases it

Usage: screenly edge-app deploy [OPTIONS]

screenly edge-app deploy [OPTIONS]

Options:

-p, --path <PATH> — Path to the directory with the manifest. Defaults to the current working directory
-d, --delete-missing-settings <DELETE_MISSING_SETTINGS> — Delete settings that exist on the server but not in the manifest

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. Defaults to the current working directory

Validate

Validates the 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. Defaults to the current working directory

Mcp

Starts the MCP (Model Context Protocol) server on stdio for AI assistant integration

Usage: screenly mcp

screenly mcp

For AI assistant integration, see the MCP Server documentation.

Screenly CLI

Installation

From Releases

Homebrew (macOS only)

Nix

Docker

Building from Source

GitHub Action

Inputs

screenly_api_token

cli_commands

cli_version

Example usage

Commands

Subcommands:

Options:

Login

Logout

Screen

Subcommands:

List

Options:

Get

Arguments:

Options:

Add

Arguments:

Options:

Delete

Arguments:

Asset

Subcommands:

List

Options:

Get

Arguments:

Options:

Add

Arguments:

Options:

Delete

Arguments:

Inject js

Arguments:

Set headers

Arguments:

Update headers

Arguments:

Basic auth

Arguments:

Bearer auth

Arguments:

Playlist

Subcommands:

Create

Arguments:

Options:

List

Options:

Get

Arguments:

Delete

Arguments:

Append

Arguments:

Options:

Prepend

Arguments:

Options:

Update

Edge app

Subcommands:

Create

Options:

List

Options:

Rename

Options:

Run

Options:

`screenly_api_token`

`cli_commands`

`cli_version`