Documentation

Set up locations and devices using the InStore device CLI

Use the InStore device CLI to bulk-load your locations and devices to a new environment.

Overview

The InStore device CLI is a Node.js-based command-line tool that simplifies the process of setting up locations and their associated devices. You can use it to do the following:
  • Create multiple locations and devices from a JSON or YAML configuration file.
  • Avoid conflicts with device dependencies and ordering.
  • Securely access APIs.
  • Receive console feedback and error logging.
  • Verify locations have been added and devices have been registered.
  • Optionally integrate the tool into your deployment scripts and automate store setup processes.

Prerequisites

Your development environment should include the following:

  • Node.js 22.x or higher
  • npm 10.x or higher

Set up your local repository

To set up your local repository for use with the InStore device CLI, complete the following steps:

  1. Clone the InStore device CLI repository, for example:

    git clone https://github.com/NebulaTerra/instore-device-cli.git
cd instore-device-cli

  2. Install the required dependencies, for example:

    npm install

  3. Make the script executable as follows:

    chmod +x index.js

  4. Create an environment file (.env) with the following variables:

    VariableDescription
    API_BASE_URLBase URL of your REST API. The default is http://localhost:5000.
    USER_IDYour user ID for authentication.
    TENANT_IDYour tenant ID for authentication.
    CONNECTION_KEYYour environment’s connection key for authentication.
    SCOPES(Optional) Comma-separated list of the scopes used by your API Client for InStore.
    TOKEN_EXPIRATION(Optional) Token expiration in seconds. The default is 3600).
    You can use our sample file as a starting point. For example:
    cp .env.example .env
nano .env

  5. Test your authentication credentials, for example:

    node index.js auth	
# Or	
./index.js auth

Create the configuration file

After setting up your repository, you need to create your configuration. We expect the configuration file to resemble the sample-location.json that we provide in GitHub. You can use JSON or YAML formats for the file. Not all lines in the sample are required; to view the subset of values we automatically validate against, see the following files in the GitHub src folder:
  • constants.mjs: pre-check validations
  • locations.mjs: post-check validations
When creating a file based on sample-location.json, verify that a particular device you plan to create is supported by our internal device dictionary. If it is, identify that device by name in the file. If a device you plan to use is not supported, contact your commercetools representative.

To include only supported devices, do the following:

  1. Log in to the InStore colleague app.
  2. Go to Manage Devices.
  3. Select a device of the type you are checking for. Alternatively, add a new device.
  4. In the Supported Devices field, view the available options.
  5. Enter the name of the supported device in the Name field of your configuration file. Make sure you spell it exactly how it appears in the Supported Devices field.

Configuration components

Most retail locations have the following devices:

  • Safe
  • Receipt or label printers
  • Cash drawers
  • Barcode scanners
  • Payment terminals or PEDs
  • Workstations

The CLI creates devices in a specific order to properly manage dependencies:

  1. Standard devices, such as safes, PEDs, printers, and scanners are created first.
  2. Cash drawers are created next, but only after any devices they rely on have already been created. For example, if a printer is required for a cash drawer, the printer must be created before the cash drawer itself.
  3. Workstations are created last because they reference all other device types.

Alias references

Use alias fields to reference devices. For example, when registering a workstation, you must identify at least a default printer and a default cash drawer as shown in the following example:

{
"name": "iPad Pro",
"type": "Workstation",
"default_PED": "PED-Flagship-01",
"default_cashdrawer": "CASH-Flagship-01",
"default_printer": "PRINT-Flagship-01",
"default_scanner": "SCAN-Flagship-01"
}
In this example, the alias that references the default PED for this workstation is PED-Flagship-01. This is a locally unique value that you specify to temporarily stand in for the device ID, which will not exist until after the device is created. You can look up the ID later in the InStore Center.

Run and validate the configuration file

Run the batch command to populate locations and devices in the specified environment. The following example shows how to do this, where sample-location.json is the name of your configuration file:
node index.js batch sample-location.json

Check your work

Feedback is provided inline while your batch is running. Errors and warnings are written to dedicated log files. After the batch is complete, confirm its success by checking for specific objects that were created by the configuration file.

  1. List all locations:

    node index.js list-locations

  2. Validate the presence of a specified location:

    node index.js validate-location LOCATION_ID

  3. Validate the presence of a specified workstation:

    node index.js validate-location LOCATION_ID WORKSTATION_ID

  4. List all devices for a specified location:

    node index.js list-devices LOCATION_ID
You can reference the inline output from these queries instead of a file by using JsonData in subsequent batch commands.
To add an individual location or device, see the Add a single location or device with the CLI.

InStore device CLI logging

In addition to writing errors to the console, the InStore Device CLI generates detailed logs for each batch operation. Logs are saved as timestamped JSON files in the current directory. There you can view detailed error reporting for failed operations.

For example, errors are logged for safe and cash drawer configurations that are incorrect and for references that are missing or incorrect. Warnings are written for data that is missing but not required.

Troubleshooting InStore device CLI

If you encounter authentication errors, verify the following:

  • Your credentials in the .env file are correct.
  • Your user account has the proper permissions in the scopes list.
  • The API endpoint is correct and accessible.

If you encounter issues during device creation, verify the following:

  • All required fields are present.
  • Referenced devices have been created.
  • Enum values match, including those for device types, statuses, and more.
  • The log file provides detailed information about failed attempts.