The command line
sitemanager is the SiteManager command line. Use it from a terminal or a command prompt, in scripts, and over SSH. Everything you can do on the pages of the web interface can also be done from here.
The command line has two ways of working. Read Service mode and direct mode first. It explains which one you are using.
For every command and flag, see the Command reference. If you have scripts written for SiteManager 2.x, see Moving from SiteManager 2.x: they still work.
Getting help
sitemanager help # all commands
sitemanager help settings # the usage of one command
sitemanager version # the version
Running sitemanager with no command, or with an unknown command, prints the list of commands.
Service mode and direct mode
Service mode talks to the SiteManager service. Every change you make is checked for the right display, locked against other jobs, and written to the audit log, exactly as if you had made it in the web interface. Use service mode whenever a SiteManager service is available. Some commands exist only in service mode.
Service mode has two forms:
- A service on this computer in local mode, the default. The command line finds it by itself and needs no login, no token and no certificate fingerprint. Every request acts as the administrator
/local, which is the name the audit log shows. - A service in network mode, on this or another computer. This needs an API token, the service's address and its certificate fingerprint. See Network mode: logging in.
Direct mode talks straight to the displays, with no service. You name the displays by address (--hosts), or by serial number (--displays), which SiteManager finds with a broadcast. Direct mode is useful from a laptop on the touch network, for scripted installs over SSH, and when no service is installed. Changes made in direct mode are not audited, take no job locks and do not check the identity of a display you named by address.
The command line chooses the mode once, before it runs, like this:
--directselects direct mode. Nothing else is tried.- A service in local mode. If the configured server is on this computer, or no server is configured, the command asks the service there whether it is in local mode. It uses a plain request to
http://127.0.0.1:8790/api/v1/version, waits at most one second, and follows no redirect. If the service answers that it is in local mode, the command uses it with no login. NoAuthorizationheader is ever sent in this case, even when a token is stored. SetSITEMANAGER_LOCAL_SERVICE=host:portif the service on this computer listens on another address and no server is configured. - A service in network mode. If an API token is available (from
--token,SITEMANAGER_TOKENor the stored login), the command uses the service over HTTPS, as described under Network mode: logging in. - Otherwise it uses direct mode.
--service selects service mode and fails if neither a local-mode service nor a token is found. The message is --service: no API token is configured, and no SiteManager service in local mode answers at http://127.0.0.1:8790, and the exit code is 4.
A service in network mode answers the plain request with a TLS error, so it is never taken for a local one. A configured server that is not on this computer is never asked. The commands --direct, help, version and logout never ask. A refused connection comes back at once. A service that accepts the connection but does not answer within a second is not taken for a local one.
In direct mode, when a SiteManager service runs on the same computer, commands that write print a warning that they bypass its audit log and job locks. If that service is in local mode, the warning advises you to leave out --direct, because the service needs no login.
--hosts needs --direct when a local-mode service runs
When a service in local mode runs on the computer, the commands go through the service, and the service takes --displays, --wall or --all, not --hosts. A script that used a command such as sitemanager settings set --hosts A,B ... on that computer now needs --direct: sitemanager --direct settings set --hosts A,B .... With --direct the command bypasses the service's audit log, job locks and identity checks, and prints a warning about that on standard error. Without --direct it stops with --hosts addresses displays directly; with a service, select displays with --displays, --wall or --all (or add --direct).
SiteManager 2.x style command lines, such as sitemanager --hosts a,b --info, are not affected. They always talk to the displays directly. See Moving from SiteManager 2.x.
Commands that exist only in service mode: whoami, tokens, users, password, displays, jobs, alerts, history and monitor. If you run one with no service to use, it stops with exit code 4 and says no service in local mode answers and no API token is configured. tokens, users and password also need network mode, as the next section says. In direct mode you can use discover, idle, settings, tracker, identify, reboot, calibrate, site, config, diagnostics, profiles, drift, capabilities and firmware. Some of them take a different set of options in direct mode. The Command reference says which.
Local mode: no login
When a service in local mode runs on this computer, there is nothing to sign in to. Run any service-mode command:
sitemanager displays
sitemanager whoami
sitemanager whoami prints local administrator (/local, role admin) and says that the service runs in local mode and needs no login.
These commands exist for users and tokens, which local mode does not have. They are available in network mode only:
users,tokensandpasswordstop with exit code 2 and the service's message,not available in local mode: SiteManager listens on this computer only and has no logins, users or API tokens; to let other computers connect, restart it with a network --listen address (for example --listen :8790). They read nothing from standard input.loginstops with exit code 4 and says that the service on this computer runs in local mode, so commands on this computer need no login.
Network mode: logging in
To use a service in network mode, which is how you reach one on another computer, you need three things: the address of the service, the fingerprint of its certificate, and an API token. login is for network mode only. A service in local mode needs no login.
- Create an API token on the Account page of the web interface. It is shown once.
- Find the certificate fingerprint. It is in the footer of the login page, and
sitemanagerd --state-dir DIR --print-fingerprintprints it on the service's computer. -
Store them with
login:sitemanager login --server https://wallpc:8790 --fingerprint AA:BB:... --token smt_...To keep the token out of your shell history and the process list, send it on standard input:
echo "$TOKEN" | sitemanager login --server https://wallpc:8790 --fingerprint AA:BB:... --token -
login checks the token with the service and prints the user it belongs to. It then saves the address, fingerprint and token in the file cli.json in your configuration folder (see Where things are). The file is readable only by you. On Linux and macOS, sitemanager refuses to use a cli.json that holds a token and can be read by other users.
The fingerprint is required. The command line never trusts a certificate the first time it sees it, and it has no switch that turns the check off. Every connection is checked against the pinned SHA-256 fingerprint, and a service that presents another certificate gets no token. The server address must start with https://.
sitemanager logout deletes the stored login. The token stays valid until you revoke it on the Account page.
sitemanager whoami shows who you are signed in as, with your role and permissions.
Without a stored login
A script can pass the same three values in environment variables or flags:
| Setting | Flag | Environment variable |
|---|---|---|
| Service address | --server |
SITEMANAGER_SERVER |
| Certificate fingerprint | --fingerprint |
SITEMANAGER_FINGERPRINT |
| API token | --token |
SITEMANAGER_TOKEN |
A flag beats the environment, and the environment beats the stored login. If nothing gives an address, the command line first looks for a service in local mode on this computer, and then uses https://127.0.0.1:8790, a network-mode service on the same computer.
Choosing displays
Commands that act on displays take a selection:
| Flag | Selects |
|---|---|
--displays S1,S2 |
Displays by serial number, separated by commas. |
--wall WALL |
Every display of a wall. Give the wall's name or its id. |
--all |
Every display of the site. |
--hosts A,B |
Displays by address. Direct mode only. |
In service mode you can combine --displays, --wall and --all.
Output
Commands print readable tables and lines. Add --json to get the service's own JSON document instead, which is the better choice in scripts. --json prints one document per command. A command that touches several settings groups at once prints an array.
With --json, an error is printed as {"error": "..."} on standard output. Every error is also printed as one line starting with sitemanager: on standard error.
sitemanager --json displays
Long operations
reboot, calibrate, firmware download, firmware rollout and profiles apply start a job. They print the job id and return at once. Add --wait to follow the job until it ends. --wait prints progress on standard error and exits with the job's outcome. It never gives up by itself, because rollouts can take hours. Add --wait-timeout 30m to stop waiting after that long. The job keeps running.
A job that needs your go-ahead stops --wait with exit code 1, and keeps waiting on the service. Answer with sitemanager jobs confirm ID, or start the command with --yes. Control-C stops waiting, never the job. Stop a job with sitemanager jobs cancel ID.
If a write is cut short by Control-C or --timeout, SiteManager does not pretend it failed or succeeded. It says the outcome is unknown, tells you which command shows the real state, and exits with 3.
Options every command takes
| Flag | Meaning |
|---|---|
--json |
Print JSON. |
--timeout D |
How long one request to the service may take. The default is 2m. |
--wait-timeout D |
With --wait, stop waiting after this long. |
The flags --server, --token, --fingerprint, --direct and --service go before the command name.
Exit codes
| Code | Meaning |
|---|---|
| 0 | Done. |
| 1 | Anything else: a cancelled or interrupted job, a job that waits for confirmation, idle when the wall is busy or could not be measured, a display that could not be read. |
| 2 | The service or a display answered with an error: an error status other than 502 and 504, a display that answered with another serial number, a display that is busy in a job, a value that was refused, a failed job, or a rollout check that is not ok. |
| 3 | Could not reach the service, or its certificate does not match the pinned one; a timeout; the service answered 502 or 504; a display could not be reached; a redirect (never followed); or a write whose outcome is not known. |
| 4 | Bad command line, or no usable configuration, for example no pinned fingerprint, no token and no local-mode service, or an unknown flag. login against a service in local mode also exits with 4. |
Some commands add rules for their own exit codes. idle exits 0 only when the wall is idle. drift, capabilities and diagnostics are described in the Command reference.
Other environment variables
These apply to direct mode and keep working from SiteManager 2.x:
| Variable | Meaning |
|---|---|
MULTI_UPDATE_URL |
The firmware catalogue address. |
MULTI_UPDATE_OS |
The catalogue's operating system filter. The default is linux-tegra+linux-tegra2. |
MULTI_UPDATE_BRANCH |
The catalogue branch. The default is stable. |
MULTI_SITEMANAGER_FIRMWARE_IMAGES |
The folder for downloaded firmware images. The default is a firmware folder in your user cache folder, in sitemanager. |
SITEMANAGER_LOCAL_SERVICE |
host:port of the service on this computer, when no server is configured. The command line asks it whether it is in local mode, and the direct-mode warning looks for it. The default is 127.0.0.1:8790. |
MULTI_UPDATE_FORCE is no longer honored. Use --allow-downgrade instead.
Examples
Read the status of all displays of a wall as JSON. On a computer that runs SiteManager in local mode this needs no login:
sitemanager --json displays
Set the OSD timeout on a wall, then save it on the displays:
sitemanager settings set --wall "Lobby wall" --settings.osd.timeout=30
sitemanager settings save --wall "Lobby wall"
Reboot every display and wait for the job to end. If the wall looks in use, the job waits for your go-ahead and --wait stops with exit code 1:
sitemanager reboot --all --wait
Check one display from a laptop, or from a computer where a local-mode service runs, bypassing the service:
sitemanager --direct settings get osd --hosts 192.0.2.11