# 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](/MMS/_api) or [Enrollment API](/App/_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:

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

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

```bash
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:

```bash
xs4face --help
```

To uninstall, remove the command and the install directory:

```bash
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](/Introduction/_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.

```bash
xs4face config env set -e accept-westeurope
```

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

### 2. Log in

```bash
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.

```bash
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:

```bash
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.

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

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

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

```text
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.

> [!note]
> The simulated device connects directly to the recognition appliance, as a real
> device does. The machine running the CLI must be able to reach the
> appliance's IP address on port 443.

### 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:

```bash
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:

```bash
#!/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:

```bash
xs4face --help
xs4face mock device --help
```

Other useful commands:

| Command | Does |
| --- | --- |
| `xs4face cloud sites devices list` | List the devices on the site |
| `xs4face cloud sites devices remove -r <server-id> -d <device-id>` | Remove a device from the site |
| `xs4face mock device heartbeat -m <mac-address>` | Send a heartbeat, so the device shows as online |
| `xs4face auth logout` | Remove the saved token |