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
~/.pixeland thepixelcommand 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/binto your PATH in your shell’s profile file when it is not there, and says which file.
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.
Windows
irm https://cli.pxsignage.com/install.ps1 | iex- Puts the command line in
%LOCALAPPDATA%\pixeland thepixelcommand 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
binfolder to your user PATH when it is not there. Open a new terminal afterwards.
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.comFirst 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.csvReplace 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.
| Command | What it does |
|---|---|
| pixel version | This command line's version and the schema it was built against |
| pixel whoami | Who the key belongs to, the organisation, and the server's release |
| pixel gql '<document>' | Send any GraphQL operation |
| pixel login | Sign 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 logout | Remove 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 ls | The media library, a page at a time: id, name, kind, size and when it was added |
| pixel playlist ls | Playlists, 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 ls | Channels, 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 ls | Schedules 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 ls | Screens, 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 export | Proof 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.