pxsignage

Command line

Use the portal from a terminal or a script: upload media, build playlists, schedule and publish channels, and read what your screens report. It signs in as you and can do only what you can do in the portal.

Install

Paste one line into a terminal. Running it again updates the command line.

Linux

curl -fsSL https://cli.pxsignage.com/install.sh | sh
  • Puts the command line in ~/.pixel and the pixel command in ~/.local/bin.
  • Needs no administrator rights and never runs sudo.
  • Uses this computer’s Node when it is Node 22 or later. Otherwise it downloads Node from nodejs.org into the same folder.
  • Checks the SHA-256 of each file it downloads, and runs the new command line once before it replaces anything.
  • Adds ~/.local/bin to your PATH in your shell’s profile file when it is not there, and says which file.

Read the script before you run it

macOS

curl -fsSL https://cli.pxsignage.com/install.sh | sh
  • macOS uses the Linux script, with the same folders. It has not been run on a Mac yet.

Read the script before you run it

Windows

irm https://cli.pxsignage.com/install.ps1 | iex
  • Puts the command line in %LOCALAPPDATA%\pixel and the pixel command in %LOCALAPPDATA%\pixel\bin. Use Windows PowerShell 5.1 or PowerShell 7.
  • Needs no administrator rights.
  • Uses this computer’s Node when it is Node 22 or later. Otherwise it downloads Node from nodejs.org into the same folder.
  • Checks the SHA-256 of each file it downloads, and runs the new command line once before it replaces anything.
  • Adds the bin folder to your user PATH when it is not there. Open a new terminal afterwards.

Read the script before you run it

Without the script

Download the command line and its checksum, check the file, and run it with Node 22 or later. On Linux, sha256sum -c SHA256SUMS checks it; on macOS, shasum -a 256 -c SHA256SUMS.

node pixel.cjs login --url https://pxsignage.com

First steps

Sign in, then upload a file, put it in a playlist, schedule the playlist on a channel, publish the channel, and follow a screen and its proof of play.

pixel login
pixel media upload welcome.mp4
pixel playlist create "Welcome"
pixel playlist add <playlist-id> <media-id>
pixel schedule set <channel-id> --playlist <playlist-id>
pixel publish <channel-id> --wait
pixel screens show <screen-id> --wait-playing
pixel plays export --from <YYYY-MM-DD> --to <YYYY-MM-DD> --out plays.csv

Replace each value in angle brackets. media upload and playlist create print the ids they make; pixel channel ls and pixel screens ls list the others. A channel reaches a screen once it is assigned to it (pixel channel assign).

Commands

pixel <command> --help shows the options of one command.

CommandWhat it does
pixel versionThis command line's version and the schema it was built against
pixel whoamiWho the key belongs to, the organisation, and the server's release
pixel gql '<document>'Send any GraphQL operation
pixel loginSign in through the browser and keep the key on this computer
pixel use <profile>Make a profile current, and set or clear the brand its commands send
pixel logoutRemove a profile and its key from this computer
pixel media upload <file> [<file> ...]Upload files to the media library, one after another; a file that fails does not stop the rest
pixel media lsThe media library, a page at a time: id, name, kind, size and when it was added
pixel playlist lsPlaylists, a page at a time: id, name, items, length and when each last changed
pixel playlist create <name>Create an empty playlist and print its id
pixel playlist show <playlist-id>A playlist and its items in order: position, kind, id, name and duration
pixel playlist add <playlist-id> <media-id> [<media-id> ...]Add media to the end of a playlist in the order given; nothing is added unless every id is found
pixel channel lsChannels, a page at a time: id, name, whether it has unpublished changes, and when it last changed
pixel channel show <channel-id>A channel's layout; for each frame, its schedules in the order of the day: days, hours, priority and playlist; and what the channel is assigned to
pixel channel assign <channel-id>Put a channel on a screen, a screen group or a location, as the channel page does; already there, it changes nothing. For a screen, says which channel it was on before and which wins now
pixel channel unassign <channel-id>Take a channel off a screen, a screen group or a location; not there, it changes nothing
pixel schedule lsSchedules on every channel, or one, a page at a time: id, channel, frame, days, hours and playlist
pixel schedule set <channel-id>Schedule a playlist on a frame of a channel for some days and hours (default: every day, all day); the same days and hours on the same frame change that schedule. Screens change only after pixel publish
pixel publish <channel-id>Publish a channel: commit a new release of it, and print the publish job that prepares the release's delivery plan. With --wait, follow the job to its end: exit 0 when it went well, 1 when it failed, 5 when --timeout passes first
pixel screens lsScreens, a page at a time: id, name, location, connectivity, last report, and what the player says the screen is showing
pixel screens show <screen-id>A screen in full: what the player reports it is showing, its channel and that channel's current release, and the release the player reports. --wait-playing waits until the screen is online and that is the current release
pixel plays exportProof of play as a CSV, the Reports page's export: asks for it, follows it until it is ready, and writes the file; what the file covers goes to stderr

Keys

pixel login gives you an address to open in a browser where you are signed in to the portal. There you approve a personal API key that acts as you, with your permissions. It is read only unless you choose read and write.

The key stays on this computer until you run pixel logout. To stop it working, revoke it in the portal under My account, Security, Personal API keys.

Update and remove

To update, run the install line again.

To remove, run pixel logout, then delete the install folder (~/.pixel, or %LOCALAPPDATA%\pixel on Windows) and, on Linux and macOS, ~/.local/bin/pixel. Then take the folder out of the profile file or user PATH the installer named.