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 trust --formula screenly/screenly-cli/screenly-cli
$ 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.

Output Formats

All list and get commands support three output formats via the global --output (-o) flag:

Format	Flag	Description
Table	--output table	Human-readable table (default)
JSON	--output json	JSON output
CSV	--output csv	CSV output, suitable for piping to files or other tools

# Human-readable table (default)
$ screenly screen list

# JSON output
$ screenly --output json asset list

# CSV output saved to a file
$ screenly --output csv screen list > screens.csv

# JSON output saved to a file
$ screenly --output json screen list > screens.json

[!NOTE] Log messages go to stderr, so redirecting stdout to a file captures only command output. Use RUST_LOG to change the log level, or RUST_LOG=off to silence logging entirely.

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, edge_app_publish_from_html

Every tool is annotated with behaviour hints (readOnlyHint, destructiveHint, idempotentHint), so MCP clients can tell read-only tools apart from ones that modify or delete data and prompt for confirmation before destructive actions.

Configuration Examples

Claude Desktop Extension (.mcpb)

For Claude Desktop, the expected install path is Desktop Extensions (Settings → Extensions) — the same idea as installing the CLI with Homebrew. Once Screenly is listed, install it there and paste your API token when prompted. No manual JSON editing required.

For testing before the listing is live, you can sideload a .mcpb from the latest release. macOS release bundles are not Developer ID–signed yet (same as the CLI .tar.gz artifacts); a browser download may be blocked by Gatekeeper. If that happens, use System Settings → Privacy & Security → Open Anyway. Details: mcpb/README.md.

The token is stored in your operating system's keychain rather than a plaintext config file.

Cursor / other clients

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 Calendar Versioning (YY.M.MICRO = two-digit year, month, and a micro number that starts at 0 for the first release in a given month and increments for any additional release in that same month).

Cargo.toml's version field is parsed by Cargo as strict SemVer, which forbids a leading zero in any numeric component. This means the month is not zero-padded: August is 8, not 08 (e.g. 26.8.0, not 26.08.0).

1. Prepare the release:

• Figure out the version: use the current two-digit year and month, and check existing tags/branches for that year and month (git tag -l "v$(date +%y).$(date +%-m).*") to pick the next MICRO — 0 if none exist yet for this month, otherwise the highest existing MICRO plus one.
• Create a release branch (e.g., release-YY.M.MICRO, like release-26.8.0).
• Update the version in Cargo.toml, action.yml, and Dockerfile
• Run cargo build to update Cargo.lock with the new version

1. Create and merge the pull request:

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

1. 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., vYY.M.MICRO, like v26.8.0) and push it to GitHub by running:

  git tag vYY.M.MICRO
  git push origin vYY.M.MICRO
  

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

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