Screenly Command Line Interface (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:

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

Commands

Explore available commands here.

MCP Server (AI Assistant Integration)

The Screenly CLI includes a built-in Model Context Protocol (MCP) server, enabling AI assistants like Claude, Cursor, and others to interact with your Screenly digital signage network.

Starting the MCP Server

$ screenly mcp

The server communicates over stdio and exposes the full Screenly API as tools.

Available Tools

| Category | Tools | |----------|-------| | Screens | screen_list, screen_get | | Assets | asset_list, asset_get, asset_create, asset_update, asset_delete | | Asset Groups | asset_group_list, asset_group_create, asset_group_update, asset_group_delete | | Playlists | playlist_list, playlist_create, playlist_update, playlist_delete | | Playlist Items | playlist_item_list, playlist_item_create, playlist_item_update, playlist_item_delete | | Labels | label_list, label_create, label_update, label_delete, label_link_screen, label_unlink_screen, label_link_playlist, label_unlink_playlist | | Shared Playlists | shared_playlist_list, shared_playlist_create, shared_playlist_delete | | Edge Apps | edge_app_list, edge_app_list_settings, edge_app_list_instances |

Configuration Examples

Cursor / Claude Desktop

Add to your MCP configuration file:

{
  "mcpServers": {
    "screenly": {
      "command": "screenly",
      "args": ["mcp"],
      "env": {
        "API_TOKEN": "your-api-token-here"
      }
    }
  }
}

Authentication

The MCP server uses the same authentication as the CLI:

• Set the API_TOKEN environment variable, or
• Run screenly login to store credentials in ~/.screenly

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

Protocol Buffers (Protobuf) Generation

Generate pb_signature.rs from signature.proto:

$ cargo install protobuf-codegen
$ protoc --rust_out . signature.proto
$ mv signature.rs src/pb_signature.rs

Release Process

This project follows Semantic Versioning (M.m.p = Major.minor.patch).

1. Prepare the release:

• Create a release branch (e.g., release-M.m.p, like release-1.0.6).
• Update the version in Cargo.toml, action.yml, and Dockerfile
• Run cargo build to update Cargo.lock with the new version

2. Create and merge the pull request:

• Create a pull request from the release branch to master
• Once approved, merge the pull request

3. Create the GitHub release:

• Make sure that you're on the master branch and have pulled the latest changes
• Create a version tag (e.g., vM.m.p, like v1.0.6) and push it to GitHub by running:

  git tag vM.m.p
  git push origin vM.m.p
  

• The release workflow will detect the version tag and create the release automatically
• Add the release notes to the GitHub release description

4. Update Homebrew:
   • Update the Homebrew repo with the latest version