XS4Face CLI

The xs4face command line interface lets you drive XS4 Face from a terminal or a script. Its main use for partners is a simulated device: a software stand-in for an XS4 Face camera that sends access requests to your site’s recognition appliance, just as a real device does.

Why use it

Testing an integration against a real camera means someone standing in front of it, and every attempt is slightly different — lighting, pose, distance. That makes results hard to reproduce and impossible to automate.

The simulated device replaces the person with an image file:

• Predictable — the same image sent to the same site gives the same result, so a test that passes once keeps passing until something actually changes.
• Repeatable — every step is a single command, so a whole scenario can be scripted and run as often as you like, including in a CI pipeline.
• No hardware needed — developers can work on the access flow without a device on their desk, and without being on site.

Typical uses are checking that a user enrolled through the Users API or Enrollment API is recognised, and that a user who has been removed, or has withdrawn consent, is no longer granted access.

Install

The CLI runs on macOS and Linux and needs Python 3.10 or later. Install the latest version with:

curl -L https://installer.global.xs4face.app/cli/installer | bash

To install a specific version, pass it to the installer:

curl -L https://installer.global.xs4face.app/cli/installer | bash -s -- 1.0.0

The installer unpacks the CLI into ~/.xs4face-cli, creates a Python virtual environment for its dependencies and adds the xs4face command to /usr/local/bin. It asks for sudo to create that link.

Check the installation with:

xs4face --help

To uninstall, remove the command and the install directory:

sudo rm -f /usr/local/bin/xs4face
rm -rf ~/.xs4face-cli

Getting started

Before you start you need access to the XS4 Face console and a site with a recognition appliance — see Getting Started.

Most commands take -e (environment) and -s (site). Once you have set an environment and added a site, both default to those values, so the commands below leave them out.

1. Set the environment

Select the environment to work against. Use accept-westeurope for development and testing, and prod-westeurope only for live sites.

xs4face config env set -e accept-westeurope

xs4face config env list shows every environment the CLI knows about.

2. Log in

xs4face auth login

A browser window opens. Sign in with your XS4 Face console account and the CLI saves the token locally for later commands.

3. Add a site

Add the site you want to test against. Its site ID is shown in the XS4 Face console.

xs4face config site add -s <site-id>

This fetches the site’s recognition appliances (servers) and makes the site the default for later commands. List the servers and their IDs with:

xs4face config env get -e accept-westeurope

4. Add a simulated device

Adding a device takes two steps: create it on the site, then commission the simulated device with the access token that is returned.

xs4face cloud sites devices create -r <server-id>

Device created on server <server-id> with access token <access-token>

xs4face mock device commission -r <server-id> -t <access-token>

Device <mac-address> commissioned to site <site-id>

The CLI generates a MAC address for the device unless you pass one with -m. Keep it — it identifies the device in the next step. The device’s certificate is stored in the CLI’s configuration, so you only commission it once.

5. Send an image

Send an access request from the device, using an image file in place of a face in front of the camera:

xs4face mock device request -m <mac-address> -i face.jpg

The CLI prints the appliance’s response, showing whether the face was recognised and access granted.

Automating tests

Because each step is a single command, a test scenario is a short script. For example, to check a set of test images against a site:

#!/usr/bin/env bash
set -euo pipefail

xs4face config env set -e accept-westeurope
xs4face config site add -s "$SITE_ID"

for image in test-images/*.jpg; do
  echo "== $image"
  xs4face mock device request -m "$DEVICE_MAC" -i "$image"
done

Commission the device once, then reuse its MAC address in every run.

More commands

Every command has built-in help, for example:

xs4face --help
xs4face mock device --help

Other useful commands: