Command reference

This page lists every sitemanager command. For how the command line works, see The command line. Run sitemanager help COMMAND for the usage of one command.

sitemanager [--server URL] [--token TOKEN] [--fingerprint FP] [--direct|--service] [--json] [--timeout D] COMMAND [ARGS]

In this reference, SELECTION means --displays S1,S2, --wall WALL or --all (and --hosts A,B in direct mode). See Choosing displays.

Each command says whether it works in service mode, in direct mode, or both. Service mode covers a service in local mode on this computer, which needs no login, and a service in network mode, which needs an API token. See Service mode and direct mode.

A service in local mode has no users, tokens or passwords. login, tokens, users and password are for network mode only.

Command	Service	Direct
login (network mode only), logout, version, help	Local	Local
whoami	Yes	No
tokens, users, password (network mode only)	Yes	No
displays, walls, rooms, jobs, alerts, history, monitor	Yes	No
discover, idle, settings, tracker, identify, reboot and calibrate	Yes	Yes
firmware, config, site, diagnostics, profiles, drift, capabilities	Yes	Yes

The display-security commands are access (service mode only), ssh-keys and update-channel (service mode, and direct mode for part of them). They are described below.

login, logout, whoami, version and help

Command	What it does
sitemanager login --server URL --fingerprint FP --token TOKEN	Network mode only. Stores the service address, its certificate fingerprint and an API token, after checking that the service accepts them. --token - reads the token from standard input. --fingerprint is required. Against a service in local mode it exits with 4 and says that no login is needed.
sitemanager logout	Deletes the stored login.
sitemanager whoami	Shows the user, role and permissions of the token. For a service in local mode it prints local administrator (/local, role admin).
sitemanager version	Prints the version of the command line.
sitemanager help [COMMAND]	Lists the commands, or shows the usage of one.

See Local mode: no login and Network mode: logging in.

tokens

Your own API tokens. Network mode only. In local mode there are no tokens, and the command exits with 2 and not available in local mode: ....

Command	What it does
sitemanager tokens [list]	Lists your tokens: id, name, role, when created and when last used.
sitemanager tokens create NAME [--role ROLE]	Creates a token and prints it once. --role gives the token a lower role than yours, for example viewer.
sitemanager tokens revoke ID	Revokes one token.
sitemanager tokens revoke --all [--yes]	Revokes all your tokens. It asks first unless you add --yes.

users

Administrators only. Network mode only. In local mode the command exits with 2 and not available in local mode: .... See Users, roles and security.

Command	What it does
sitemanager users [list]	Lists users with their role and the number of tokens and sessions.
sitemanager users add NAME --role ROLE --password-stdin	Adds a user. ROLE is admin or viewer. The password is read from standard input.
sitemanager users role NAME ROLE	Changes a user's role to admin or viewer.
sitemanager users password NAME --password-stdin	Sets a user's password, read from standard input. This ends that user's sessions but keeps their tokens.
sitemanager users remove NAME [--yes]	Removes a user. It asks first unless you add --yes.
sitemanager users revoke NAME [--tokens] [--sessions]	Ends the user's API tokens, sessions, or both. With neither flag it ends both.

A password is never accepted as an argument, because it would end up in your shell history and in the process list. Send it on standard input:

echo "$PASSWORD" | sitemanager users add maria --role viewer --password-stdin

With --json, commands that would ask a question need --yes, because a question cannot be answered inside a JSON stream.

password

Changes your own password. Network mode only. In local mode the command exits with 2 and not available in local mode: .... The current password is on the first line of standard input and the new one on the second:

printf '%s\n%s\n' "$CURRENT" "$NEW" | sitemanager password --password-stdin

displays

Service mode only.

Command	What it does
sitemanager displays [list]	Lists every display: serial number, name, model, wall, address, state, firmware and label. The NAME column is the name you gave the display, or -. The LABEL column is what the web interface shows: the name, or row:column (counting from 1) for an unnamed display on a wall, or the serial number.
sitemanager displays show SERIAL	Shows one display, including its capabilities and last error.
sitemanager displays add IP	Adds the display at an address to the site.
sitemanager displays remove SERIAL [--release-first \| --keep-locked]	Removes a display from the site. Its status history is kept. See history. For a display SiteManager holds an access key for, you must choose one of the two options. See Removing a secured display.
sitemanager displays rename SERIAL NAME	Names a display. This changes the name in SiteManager only.

Removing a secured display

A display that SiteManager holds an access key for is not removed without a choice, because it would stay locked. Without an option the command is refused and says: Release this display before removing it, or it stays locked until someone uses Reset API access on its on-screen menu. Give one of:

• --release-first: release the display (it is open to every tool again), then remove it. If the release fails, the display stays in the site and the command says so.
• --keep-locked: remove the display and forget its key. The display stays locked until someone uses Reset API access on its on-screen menu.

Give only one of the two. See Display security.

walls

Service mode only. Lays out walls without the web interface. See Walls and Cornerstone files. A wall is named by its ID, the first column of walls list. A member is a display serial number or planned:PID for a planned display.

A slot is written ROW:COL, counting from 1, the same as a display's label. 1:1 is the top row, first column. The HTTP API counts columns and rows from 0. The command line converts.

Lengths such as --gap take pixels (10 or 10px) or millimetres (6.3mm). Millimetres are turned into whole pixels at the wall's pixel pitch.

• sitemanager walls [list] lists the walls.
• sitemanager walls show ID shows one wall: its layout, members, planned displays and problems.
• sitemanager walls models lists the display model catalogue: MT557D, MT556XNB and MT556UNB, with resolution, pixel pitch, active area and bezel.
• sitemanager walls add NAME [LAYOUT FLAGS] makes a wall, with a layout if you give flags.
• sitemanager walls layout ID LAYOUT FLAGS changes a layout. Only the flags you give change.
• sitemanager walls plan ID --fill adds a planned display to every empty slot.
• sitemanager walls plan ID add ROW:COL [--name N] [--serial S] plans one slot. sitemanager walls plan ID add --free X,Y plans a free position on a wall without a grid.
• sitemanager walls plan ID remove PID removes a planned display.
• sitemanager walls bind ID PID SERIAL makes a real display take the place of a planned one.
• sitemanager walls place ID MEMBER ROW:COL moves a display to a slot. A display already there swaps places.
• sitemanager walls rotate ID MEMBER DEG turns one display to 0, 90, 180 or 270 degrees. sitemanager walls rotate ID --all DEG turns every display.
• sitemanager walls undo ID and sitemanager walls redo ID step back and forward through the wall's changes. The history is kept in memory, so a restart clears it.
• sitemanager walls export ID [--out FILE] writes the wall's design to a file, or to standard output.
• sitemanager walls import ID FILE [--dry-run] replaces the wall's design from an export. sitemanager walls import --new FILE [--name N] [--dry-run] makes a new wall from one. --dry-run saves nothing and says what would change.

Layout flags:

• --model M copies the model's size, pixel pitch and bezel into the wall. --model "" makes the wall custom.
• --columns N, --rows N, --rotation R
• --display-size WxH, --pitch-mm P
• --gap L, or --gap-x L and --gap-y L
• --bezel none|pixels|millimetres, --bezel-mm L,R,T,B
• --origin X,Y
• --rotate-displays turns every display to the wall's rotation too.

walls outputs

An extra output is a screen beside the wall's grid that is not one of its grid displays. See Extra outputs beside a wall.

sitemanager walls outputs ID
sitemanager walls output add ID (--display SERIAL | --name NAME --resolution WxH) [--rotation R] [--video-output]
                              [--beside grid|MEMBER] [--side right|below|left|above] [--align start|centre|end]
                              | [--at X,Y]
sitemanager walls output set ID MEMBER [--name N] [--resolution WxH] [--rotation R] [--video-output | --no-video-output]
sitemanager walls output move ID MEMBER (--side S [--align A] [--beside T] | --at X,Y)
sitemanager walls output remove ID MEMBER

• outputs lists the extra outputs of a wall.
• output add adds one. Give --display SERIAL for an enrolled display that is on no wall, or --name and --resolution for a new output that SiteManager does not manage. --video-output ticks Configure as Canvus video output. The output snaps to the outside edge of the grid (--beside grid, the default) or to another extra output. --side and --align say which edge and how it lines up. --at X,Y places it exactly, in graphics pixels.
• output set changes an output. --resolution is for new outputs only.
• output move snaps an output beside something else, or places it exactly.
• output remove deletes a new output, or takes a MultiTaction screen off the wall.

A member is the display's serial number or output:NAME. For example, this adds a plain Teams screen below the grid, centred:

sitemanager walls output add lobby-wall --name Teams --resolution 1920x1080 --side below --align centre

rooms

Service mode only. Reads projector rooms. See Projector rooms.

• sitemanager rooms [list] lists the rooms.
• sitemanager rooms show ID shows one room: surfaces, overlap bands with their fade and crop, and problems. A band line reads like 1232 px overlap, fade 1232, crop 0 | 0: the overlap width, the width faded across, and the pixels the two projectors give up.
• sitemanager rooms export ID [--out FILE] writes the room to a file, or to standard output.
• sitemanager rooms import ID FILE [--dry-run] replaces a room from an export, keeping its id and name. sitemanager rooms import --new ID FILE [--name N] [--dry-run] makes a new room from one.
• sitemanager rooms undo ID and sitemanager rooms redo ID step back and forward through the room's changes, in memory.

discover

Command	What it does
sitemanager discover broadcast	Finds displays on the local network with a broadcast.
sitemanager discover sweep CIDR	Checks every address in an IPv4 range, at most 4094 addresses (/20 or smaller).

Both commands list what they found: address, serial number, model and firmware. They do not add displays. Use displays add IP for that. In service mode the output also names known displays that turned up at a new address. A sweep sends a small read request to every address in the range.

idle

sitemanager idle SELECTION asks whether anyone is using the wall. It prints the verdict, and a table with each display's address, number of connections, traffic spread and whether it is busy.

The exit code is 0 only when the wall is idle. A busy wall, and a wall that could not be measured, both exit 1, so a script can chain on it. See the idle-wall check.

settings

Command	What it does
sitemanager settings registry	Lists every setting: its flag, kind, limits, whether it needs saving, and its label.
sitemanager settings get GROUP SELECTION	Reads one group of settings from the displays.
sitemanager settings set SELECTION --FLAG=VALUE ...	Changes settings.
sitemanager settings save SELECTION	Saves pending changes on the displays.
sitemanager settings discard SELECTION	Throws pending changes away.
sitemanager settings unsaved SELECTION	Shows which displays have pending changes.

The groups are network, osd, picture, remote-control, ssh, syslog, tuio, standby and video.

settings set takes one flag per setting. They are generated from the service's list, so settings registry always shows the current ones.

Flag	Kind	Allowed values	Saved	Meaning
--settings.network.configuration	enum	dhcp, manual	yes	Address configuration
--settings.network.address	IPv4		yes	IP address
--settings.network.netmask	IPv4		yes	Netmask
--settings.network.gateway	IPv4		yes	Gateway
--settings.network.dns1	IPv4		yes	DNS server 1
--settings.network.dns2	IPv4		yes	DNS server 2
--settings.network.proxy.host	text		yes	Proxy host
--settings.network.proxy.port	whole number	1 to 65535	yes	Proxy port
--settings.network.proxy.user	text		yes	Proxy user
--settings.network.proxy.password	text		yes	Proxy password (secret, write-only)
--settings.osd.allow-touch	true or false		yes	Whether touch operates the on-screen display
--settings.osd.timeout	whole number	0 to 6600	yes	OSD timeout in seconds
--settings.picture.brightness	number	0 to 1	yes	Brightness
--settings.remote-control.enabled	true or false		yes	Remote control on or off
--settings.remote-control.port	whole number	1 to 65535	yes	Remote control port
--settings.ssh.enabled	true or false		yes	SSH on or off
--settings.syslog.enabled	true or false		yes	Syslog on or off
--settings.syslog.host	text		yes	Syslog host
--settings.syslog.port	whole number	1 to 65535	yes	Syslog port
--settings.syslog.protocol	enum	udp, tcp	yes	Syslog protocol
--settings.syslog.min-severity	enum	debug, info, warning, error, critical	yes	Minimum severity
--settings.tuio.enabled	true or false		yes	TUIO on or off
--settings.tuio.host	text		yes	TUIO host
--settings.tuio.port	whole number	1 to 65535	yes	TUIO port
--settings.tuio.packet-size	whole number	1 to 65535	yes	TUIO packet size
--settings.tuio.hands	true or false		yes	Send hands
--settings.tuio.fingers	true or false		yes	Send fingers
--settings.tuio.objects	true or false		yes	Send objects
--power.standby.enabled	true or false		no	Standby
--video.source	enum	osd, external	no	Video source

For displays whose firmware supports them, the osd group also takes these flags. A display that lacks them is sent nothing and the command says so.

• --settings.osd.orientation (0, 90, 180 or 270, saved): how the panel is turned clockwise from landscape. For one display at a time; a profile refuses it. See Set the orientation.
• --settings.osd.trigger-hold-seconds (whole number, 3 to 15, saved): how long an open hand is held in a bottom corner to open the menu.
• --settings.osd.pin (4 to 8 digits, applies at once, write-only): the operator PIN. It is never printed. An empty value is refused.
• --remove-pin: removes the operator PIN. Do not give it together with a PIN. In the SiteManager 2.x form it is --settings.osd.remove-pin. See Set an operator PIN.

The video signal states (--video.external-signal-state and --video.internal-signal-state) are reported by the display and can be read but not set.

Notes:

• Settings marked Saved: yes stay unsaved on the display until you run settings save. Standby and video source take effect at once and are not saved.
• A value outside the allowed range is refused before anything is sent.
• If you set settings from several groups in one command, SiteManager sends one request per group. If a display refuses a group, the exit code is 2, and the other groups are still applied.
• A secret, such as the proxy password, is accepted as a flag value and never printed. A read shows <hidden>.
• settings set accepts --hosts in direct mode only. While a service in local mode runs on the computer, add --direct to use --hosts. See Service mode and direct mode.

sitemanager settings set --displays R0000001A,R0000002A --settings.osd.timeout=30 --settings.picture.brightness=0.7
sitemanager settings save --displays R0000001A,R0000002A

tracker

Tracker parameters are named Extension/parameter, for example Fingers/edge-limit.

Command	What it does
sitemanager tracker schema DISPLAY	Lists the parameters a display has: range, default, step and description. DISPLAY is a serial number, or use --displays SERIAL.
sitemanager tracker get SELECTION [--params E/p,...]	Reads parameters. Without --params it reads all of them.
sitemanager tracker set SELECTION E/p=V ...	Sets one or more parameters. They stay unsaved until settings save.
sitemanager tracker copy --from SERIAL --to S2,S3 [--params E/p,...]	Copies parameters from one display to others. Without --params it copies all of them.

sitemanager tracker set --wall "Lobby wall" Fingers/edge-limit=3

identify

sitemanager identify SELECTION [--text TEXT] [--seconds N] shows a text on the screens. Without --text each display shows its name or serial number. --seconds is 1 to 60, and 10 by default.

reboot and calibrate

Command	What it does
sitemanager reboot SELECTION [--yes] [--wait]	Restarts displays.
sitemanager calibrate SELECTION [--yes] [--wait]	Runs geometry calibration.

Both check first whether the wall is idle and whether settings are unsaved. If either is a problem, the job waits for a go-ahead. --yes goes ahead anyway. In service mode they start a job, print its id and return, unless you add --wait. In direct mode they run in the foreground.

jobs

Service mode only.

Command	What it does
sitemanager jobs [list] [--limit N]	Lists jobs. --limit is 1 to 200.
sitemanager jobs show ID	Shows a job: state, per-display steps and the last log lines.
sitemanager jobs cancel ID	Cancels a job.
sitemanager jobs confirm ID [--prompt N]	Answers a job that waits for your go-ahead. It prints what it confirms. --prompt names the request number, which is the one the job shows now by default.
sitemanager jobs wait ID	Follows a job until it ends, and exits with its outcome.

firmware

Command	What it does
sitemanager firmware catalogue [--refresh]	Lists the firmware versions in the catalogue. --refresh fetches the list again instead of using the copy from the last 10 minutes.
sitemanager firmware cache	Lists the images in the cache with their SHA-256 checksum.
sitemanager firmware download VERSION [--source SOURCE] [--wait]	Downloads an image into the cache as a job. --source names a catalogue source, as firmware catalogue shows it, for example legacy for the update server. By default SiteManager uses the only available source that lists the version.
sitemanager firmware import FILE	Imports a .swu file, up to 2 GiB.
sitemanager firmware remove SHA256	Removes an image from the cache. Give all 64 characters of the checksum.
sitemanager firmware check SELECTION IMAGE	Reads the displays and reports what a rollout would do. It sends nothing.
sitemanager firmware rollout SELECTION IMAGE [options]	Starts a staged rollout as a job.
sitemanager firmware watch	Lists the displays that SiteManager will check again after a firmware update. See Firmware re-check.

In these commands IMAGE is either --image SHA256 or --version V. Give exactly one.

Options of check and rollout:

Option	Meaning
--image SHA256 or --version V	The cached image to install. Give exactly one.
--canary SERIAL	The display to update first, alone. The default is the first one.
--batch N	Displays per batch after the canary. The default is 4.
--concurrency N	Uploads at once within a batch. The default is 2.
--allow-downgrade	Also install an image that is not newer than the display's firmware.
--yes	Do not wait for a busy wall. The verdict is logged. (rollout only.)
--wait	Follow the rollout job to its end. (rollout only.)

In direct mode firmware works on the displays you name with --hosts, in the foreground. The catalogue address is --catalogue URL, or the environment variable MULTI_UPDATE_URL.

See Firmware for what a rollout does.

Firmware re-check

sitemanager firmware watch lists the displays that have been updated and are still to be checked. It works through the service and has no direct mode, because the list lives in the service. The columns are NAME, EXPECTED (the version the update installed), DUE (when SiteManager checks next, in your local time) and STATE: waiting to confirm, confirmed or not reported. When there is nothing to check it says No displays to check again. --json prints the service's answer.

sitemanager displays show SERIAL has a line firmware start: that says how the display's firmware started, in the words of the display's page: confirmed, waiting for the display to confirm; SiteManager checks again at 20:33, or SiteManager checks again at 20:47. For a display that does not say and is not watched, the line is not shown. See Firmware re-check.

config

Generate, preview, apply, import and restore the Cornerstone files. See Walls and Cornerstone files.

Command	What it does
sitemanager config generate [--out DIR] [--force]	Saves the generated files into a folder (the current folder by default). It never overwrites a file without --force, does nothing if any file would be refused, and will not write into the folder of a configured Cornerstone file. Use apply for those.
sitemanager config preview	Shows a comparison of each generated file with the one on the computer.
sitemanager config apply [--yes] [--files LIST]	Writes the files after showing the comparison. It asks Apply these files? [y/N] unless you add --yes. --files limits it to some of screen.xml,config.txt,mt-canvus.ini. With --json you must add --yes.
sitemanager config import [options]	Reads existing Cornerstone files into the site. It only previews unless you add --apply.
sitemanager config backups	Lists the backups.
sitemanager config restore ID [--yes]	Puts a backup's files back. It backs up the current files first and asks unless you add --yes.

Options of config import:

Option	Meaning
--screen-xml FILE, --config-txt FILE, --canvus-ini FILE	The files to read.
--from-disk	Read the configured Cornerstone files of the computer instead.
--wall WALL	An existing wall to put the displays on.
--platform P	The screen.xml dialect: linux, windows or darwin.
--apply	Save the import.

mt-canvus.ini is generated only if the site has video outputs. When the service has no existing mt-canvus.ini to edit, and in direct mode, config generate saves only the output sections, as mt-canvus-outputs.ini. That file is not a replacement for mt-canvus.ini.

In direct mode the same commands work on files, with no service:

Option	Meaning
--site SITE.JSON	The site file for generate, preview and apply. Create it with config import --out SITE.JSON, which also creates a missing file.
--screen-xml, --config-txt, --canvus-ini	The files that apply, preview and restore use.
--cornerstone-user USER	Use another user's default paths.
--backup-dir DIR	Where backups go. The default is config-backups in the configuration folder.
--against DIR	With preview: compare with the three files in a folder.
--probe	With import: read each display's identity. Without it, a host that is not already in the site file is kept as written.

Direct mode follows the same preview, hash and backup rules as the service. It warns when a service runs on the same computer, and the service's audit log does not see these changes.

site

sitemanager site import-mtspf FILE [--apply] [--probe] [--wall WALL] reads a project file saved by SiteManager 2.x. It shows a preview and saves nothing unless you add --apply. See Moving from SiteManager 2.x.

Option	Meaning
--apply	Import the project.
--probe	Read each display at its address. Needed for entries that carry no serial number.
--wall WALL	An existing wall to put the displays on. The default is a new wall named after the project.
--out SITE.JSON	Direct mode only, and required there. The site file to merge into. It is created if missing.

A project file can be up to 1 MiB.

diagnostics

Collects a support bundle as a zip file. See Diagnostics and capabilities.

sitemanager diagnostics [--displays SERIAL,...] [--include CATEGORY,...] [--out FILE|-] [--force]
sitemanager --direct diagnostics (--hosts ADDRESS,... | --displays SERIAL,...) [--include CATEGORY,...] [--cornerstone-user USER] [--out FILE|-] [--force]

Option	Meaning
--displays	The displays to include. In service mode the default is every display.
--include	Also collect files of the MultiTaction products from the computer the service runs on (with --direct, the computer the command runs on). Off by default. The categories, separated by commas: canvus, canvus-server, showcase, launcher, crash-dumps, or all. Only an administrator can include crash-dumps: a viewer who asks for it, or for all, is refused and nothing is collected. The files go in computer/<category>/ in the zip. See Files from this computer.
--cornerstone-user	Direct mode only: whose home folder holds the per-user files. The default is you. In service mode the service uses its own --cornerstone-user.
--out FILE	Where to save the zip. The default is sitemanager-diagnostics-<site>-<UTC time>.zip in the current folder, with the name the service suggests. In direct mode it is sitemanager-diagnostics-<UTC time>.zip. - writes to standard output.
--force	Replace an existing file. A symbolic link is never replaced.

Displays are read four at a time, up to 150 seconds each, so 64 displays can take about 40 minutes.

Exit codes: 0 when everything was collected, 2 when any item failed, timed out or was cut short, 3 when no display, or the service, could be reached. An item that is skipped in the manifest, such as a folder the service has no permission to read (no permission to read <path>), a product that is not installed, or a file left out for its size, is not a failure and does not change the exit code.

profiles

See Profiles and drift.

Command	What it does
sitemanager profiles [list]	Lists profiles.
sitemanager profiles show ID	Shows one profile: its settings, tracker parameters and what it applies to.
sitemanager profiles set ID --file FILE	Creates or replaces a profile from a JSON file.
sitemanager profiles delete ID	Deletes a profile that nothing uses.
sitemanager profiles assign SERIAL ID	Gives a display a profile. Use --clear in place of ID to take it off.
sitemanager profiles assign-wall WALL ID	Gives a wall a profile. Use --clear in place of ID to take it off.
sitemanager profiles apply ID [SELECTION] [--save] [--yes] [--wait]	Writes the profile's differing values to displays, as a job.
sitemanager --direct profiles apply --file FILE SELECTION [--save] [--yes]	Applies a profile file to displays directly, in the foreground.

A profile file looks like this:

{
  "id": "lobby",
  "name": "Lobby wall",
  "notes": "",
  "settings": {"picture": {"brightness": 0.7}},
  "tracker": {"Fingers/edge-limit": 3}
}

settings uses the groups and keys of sitemanager settings registry, for example osd and timeout. A profile cannot hold a display's network address, netmask or configuration. A secret in the file is sent and stored, never printed. Write {"set": true} in place of a secret to keep the stored value.

profiles set sends the version it read first, so it refuses (exit 2) to overwrite a profile that someone else changed in the meantime.

profiles apply writes only the values that differ. Without --save the changes stay unsaved on the displays. With --save it saves each display whose groups were all applied, and refuses a display that already holds other unsaved changes unless you add --yes. A profile that sets the video source, standby or the network first checks whether the wall is in use, and stops unless you add --yes. With --wait the exit code is 0 when the job succeeded and 2 when it failed.

In direct mode SELECTION is --hosts A,B or --displays S,.... Direct mode applies the file in the foreground, with no audit log and no job lock. --wall, --all and --wait do not exist there. In direct mode only profiles apply --file works. Every other profiles command needs the service.

drift

See Drift.

Command	What it does
sitemanager drift [show [SERIAL]]	Shows the last drift check: displays against their profiles and files against the site.
sitemanager drift check [SELECTION]	Runs a check now. It only reads. By default it checks every display that has a profile.
sitemanager --direct drift --file PROFILE.JSON SELECTION	Compares displays with a profile file. This is the only form that works in direct mode.

Exit codes:

Code	Meaning
0	Everything that was compared is in sync, or has no profile.
2	Something drifted, or a file differs.
3	Something could not be checked, or nothing was checked at all (no display has a profile and there are no files). An empty check is not a clean one.
4	Bad command line.

A drift wins over an unknown, so a script that gates on exit code 2 sees drift even when something else could not be checked. A file reported as not-generated is shown but does not change the exit code.

capabilities

See Diagnostics and capabilities.

sitemanager capabilities [SERIAL... | --displays S,...] [--probe]
sitemanager --direct capabilities (--hosts A,B | --displays S,...)

Without --probe, the service prints what its last probe found, for every display unless you name some. --probe reads the named displays first and needs at least one serial number. Direct mode always reads the display, with two read requests each.

Exit codes: 0 when every display is advertised or none, 3 when one is unknown or not-probed (or cannot be reached), and 4 for a bad command line.

access

Shows and changes the security of displays: their encrypted connection and their access keys. Service mode only, because the service holds the keys. A command that talks to a display directly cannot hold a key. When the display asks for one, the command says This display is secured by a SiteManager service. Run the command through that service, or release the display there first. See Display security and Secure your displays.

sitemanager access [list]
sitemanager access show SERIAL
sitemanager access secure SELECTION [--wait]
sitemanager access change-key SELECTION [--wait]
sitemanager access release SELECTION [--wait]
sitemanager access trust SERIAL
sitemanager access policy [--secure-new-displays on|off]

• access or access list prints one line for each display: name, serial number, connection (not encrypted, encrypted, identity changed, and the others in Display security), access (open, secured, secured by another tool, reset on the display) and the pinned certificate, shortened. Below it, a line for each display that needs attention says what to do, and the state of the setting for new displays.
• access show SERIAL shows one display in full, including the whole pinned certificate (a fingerprint, not a key), the port, when the key was set and what the display says its access is.
• access secure, access change-key and access release start a job for a selection (--displays S1,S2, --wall WALL, --all, or serial numbers as arguments). --wait follows the job to its end. They never wait on Standby. They are the commands behind Secure, Change access keys and Release on the Security page.
• access trust SERIAL accepts the certificate a display now presents. It works only after SiteManager has said the identity changed, or that the display came back from older firmware. Otherwise it is refused with This display's identity has not changed, so there is nothing to trust. After a return from older firmware it also changes the display's access key.
• access policy shows the setting Secure new displays when they are added. --secure-new-displays on or off changes it. It is off by default.

An access key is never printed, by any command and in any output, with or without --json.

ssh-keys

Lists, adds, removes and checks the SSH keys of displays whose firmware manages them. See Manage SSH keys.

sitemanager ssh-keys SERIAL
sitemanager ssh-keys add SELECTION (--key LINE | --key-file FILE) [--wait]
sitemanager ssh-keys remove SELECTION (ID | FINGERPRINT) [--wait]
sitemanager ssh-keys check (--key LINE | --key-file FILE)
sitemanager ssh-keys password-login-off SERIAL
sitemanager ssh-keys reviewed SERIAL

• ssh-keys SERIAL lists the display's keys (type, fingerprint, comment and id) and whether SSH and password login are on.
• ssh-keys add adds a public key to a selection (serial numbers, --displays, --wall or --all) as a job. Give the key as a line (--key) or as a file (--key-file). --wait follows the job. Each display's step says Added or Already there. A display whose firmware does not manage keys is skipped with the reason.
• ssh-keys remove removes one key from a selection. The last argument names the key: its fingerprint (SHA256:…, as ssh-keygen -l prints it) or its 16-character id. Each step says Removed or Not on this display.
• ssh-keys check reads a key line and says what it is, or why a display would refuse it. It sends nothing.
• ssh-keys password-login-off SERIAL ends the one-hour window in which password login is on. SiteManager has no command to turn password login on: the display allows that only from its on-screen menu.
• ssh-keys reviewed SERIAL records that you checked the keys of a display that came back from older firmware.

A pasted private key is refused with This looks like a private key. Never paste a private key here. Paste the public key (the .pub file). and is not sent or repeated. The comment of a key is shown in the audit log, so do not put secrets in it.

update-channel

Shows and changes where a display looks for firmware: an update server address and a branch. This is the display's own setting. It is not SiteManager's own catalogue (see firmware). See Set where displays look for firmware.

sitemanager update-channel [show] SERIAL...
sitemanager update-channel set (--displays S,... | --wall WALL | --all | SELECTION...) [--url URL | --default-url] [--branch B | --default-branch] [--wait]
sitemanager update-channel check [--url URL | --default-url] [--branch B | --default-branch]
sitemanager --direct update-channel [show] --hosts A,B
sitemanager --direct update-channel set --hosts A,B [--url URL | --default-url] [--branch B | --default-branch]

• update-channel SERIAL... prints, for each display, the address, whether it is a signed catalogue (the address ends in .json) or a legacy update server, the branch and where it comes from: default, set here or set by the display's environment. A display whose firmware cannot change its update server is shown with the reason.
• update-channel set starts a job for a selection. --url and --branch set a value, --default-url and --default-branch return it to the display's default. A value you leave out keeps what the display has. --wait follows the job.
• update-channel check applies the display's own rules to a value and sends nothing. The rules: an address that starts with http:// or https:// and names a host, with no user name or password, no ? part and no # part, at most 512 characters; a branch of lower-case letters, digits and dashes, starting with a letter or digit, at most 32 characters. A value that breaks them is refused with a plain sentence that ends Nothing was sent.
• An address that the display's environment fixes wins over the stored setting. A change is stored but takes effect only once the environment's address is removed. An address with a user name or password in it is printed with those replaced by …@.
• In direct mode, with --hosts, SiteManager reads the display's capabilities first and then changes the display at once, with no job and no audit entry.

Exit codes of update-channel: 0 done; 1 a display refused or failed; 3 a display could not be reached or the outcome is not known; 4 a bad command line.

alerts

Service mode only. See Alerts. Changing anything needs a user who may change the site, an administrator.

Command	What it does
sitemanager alerts [list]	Lists the active alerts.
sitemanager alerts history [--limit N]	Shows the alert log: fired, resolved, acknowledged and dropped alerts. --limit is 1 to 1000, 200 by default.
sitemanager alerts ack ID	Records that you have seen an alert.
sitemanager alerts rules [--set FILE]	Shows the rules, or replaces all of them with the list in a JSON file.
sitemanager alerts channels [--set FILE]	Shows the channels (credentials only as set or not set), or replaces all of them from a JSON file.
sitemanager alerts test CHANNEL	Sends one test message through a channel.
sitemanager alerts status	Shows whether alerting works, what it has lost, and the delivery state of each channel.

alerts status exits with 1 when alerting is off. For the other commands, exit code 2 means the service refused (a viewer's token gets a 403 on every command that changes something), and 3 means the service or a channel's destination could not be reached.

--set FILE replaces the whole list. --set - reads the file from standard input. A rules file is a JSON array, or the document that sitemanager --json alerts rules prints. The command sends the version it read first, so it refuses (exit 2) to overwrite a change someone else made in the meantime.

A channels file is a JSON array, or {"channels": [...]}. A channel left out of the list is deleted. A credential is written as one of:

• {"value": "..."} to set a new value;
• {"clear": true} to remove it;
• {"set": true}, or left out, to keep the stored value.

For example, a webhook channel:

{
  "channels": [
    {
      "id": "ops-hook",
      "name": "Operations webhook",
      "kind": "webhook",
      "enabled": true,
      "minSeverity": "warning",
      "webhook": {
        "url": {"value": "https://example.com/hooks/sitemanager"},
        "headerName": "Authorization",
        "headerValue": {"value": "Bearer ..."},
        "hmacSecret": {"value": "..."}
      }
    }
  ]
}

Run sitemanager --json alerts channels to see the shape of the channels that exist. Email channels use email with host, port, security, from, to (a list), username and password. Syslog channels use syslog with address, protocol, facility and appName.

history

Service mode only. See Monitoring and history.

sitemanager history SERIAL [--metric M] [--range R | --from T --to T] [--points N]
sitemanager history SERIAL --csv [--range R | --from T --to T]
sitemanager history --wall WALL --metric M [--range R | --from T --to T] [--points N]
sitemanager history --removed
sitemanager history SERIAL --delete [--yes]

Option	Meaning
--metric M	One of cameraFps, idleBaseline, idleSpread, online, psuPower, temperature, trackerFps and trackerRestarts. The default for a display is temperature. A wall needs --metric.
--range R	1h, 6h, 24h, 7d, 30d or 1y. The default is 24h.
--from T --to T	A time range, as RFC 3339 times. Never combine them with --range. A range is at most 366 days.
--points N	At most this many points, from 1 to 1000. The default is 500.
--csv	Writes the service's CSV to standard output, unchanged: time,metric,min,max,avg,n, one row per metric and point, every metric of the display.

--removed lists the serial numbers of removed displays whose history is kept. --delete deletes the history of a removed display for good. Only an administrator can do it, it is written to the audit log, it asks first unless you add --yes, and it is refused while the display is still in the site.

Times are UTC. A row is a time slot that holds data, so a gap in a chart is a gap in the table. The display API reports one temperature, so that is the only one recorded.

monitor

Service mode only. See How often displays are read.

Command	What it does
sitemanager monitor [polling]	Shows how often each display is read now, until when it is focused and when it was last read.
sitemanager monitor focus SERIAL... [--seconds N]	Reads the displays every 2 seconds for N seconds, from 1 to 600 (120 by default), then returns to normal. It returns at once.

Focus changes nothing that is stored, so a viewer's token is enough. It is not recorded in the audit log.