Documentation

Set up locations and devices using the InStore device CLI

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

InStore device CLI overview

The InStore device CLI is a Node.js command-line tool for setting up locations and devices in bulk. Use it to do the following:
  • Create multiple locations and devices from a JSON or YAML configuration file.
  • Avoid conflicting device dependencies and ordering.
  • Securely access APIs.
  • Receive console feedback and error logs.
  • Verify that locations are added and devices are registered.
  • Integrate with deployment scripts to automate store setup.

Prerequisites

Before you begin, ensure your environment includes the following:

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

Set up your local repository

To set up your local repository for the InStore device CLI, follow these steps:

  1. Clone the repository:

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

  2. Install dependencies:

    Install dependenciesshell
    npm install

  3. Make the script executable:

    Make the script executableshell
    chmod +x index.js
  4. Create a .env file with the following variables:
    VariableDescription
    API_BASE_URLBase URL of your REST API. Default: http://localhost:5000.
    USER_IDUser ID for authentication.
    TENANT_IDTenant ID for authentication.
    CONNECTION_KEYEnvironment connection key for authentication.
    SCOPES(Optional) Comma-separated list of scopes for your API Client for InStore.
    TOKEN_EXPIRATION(Optional) Token expiration in seconds. Default: 3600.
    You can use the sample file as a starting point:
    Copy and edit the sample .env fileshell
    cp .env.example .env
nano .env

  5. Test your authentication credentials:

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

Create the configuration file

After setting up your repository, create a configuration file based on sample-location.json. You can use JSON or YAML format. Not all fields in the sample are required. For details on which values are validated, see the constants.mjs (pre-checks) and locations.mjs (post-checks) files in the GitHub src folder.
When adding devices, verify that each device is supported by the 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 the InStore support team. To check supported devices, follow these steps:
  1. Log in to the InStore colleague app.
  2. Go to Manage Devices.
  3. Select a device type or add a new device.
  4. In the Supported Devices field, view the available options.
  5. Enter the device name in the name field of your configuration file. Use the exact spelling from the Supported Devices field.

Configuration components

Most retail locations include the following device types:

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

The CLI creates devices in the following order to manage dependencies:

  1. Standard devices, such as safes, PEDs, printers, scanners.
  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, as they reference other device types.

Alias references

Use alias fields to reference devices in your configuration. For example, when registering a workstation, specify at least a default printer and cash drawer:

Workstation configuration examplejson
{
    "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, PED-Flagship-01 is a locally unique alias that temporarily stands in for the device ID until the device is created. You can look up the device ID later in the InStore Center.

Run and validate the configuration file

To create locations and devices, run the batch command with your configuration file, where sample-location.json is the name of your configuration file:
Run the batch commandshell
node index.js batch sample-location.json
Feedback is provided in the console while the batch runs. Errors and warnings are also written to log files.

After the batch completes, confirm success by checking for the created objects:

  1. List all locations:

    List all locationsshell
    node index.js list-locations

  2. Validate a specific location exists:

    Validate a location existsshell
    node index.js validate-location LOCATION_ID

  3. Validate a specific workstation exists:

    Validate a workstationshell
    node index.js validate-location LOCATION_ID WORKSTATION_ID

  4. List all devices for a location:

    List devices for a locationshell
    node index.js list-devices LOCATION_ID
You can use the inline output from these commands as input for subsequent batch operations by referencing JsonData.
To add a single location or device, see Add a single location or device with the CLI.

InStore device CLI logging

The InStore device CLI writes errors to the console and generates detailed logs for each batch operation. Logs are saved as timestamped JSON files in the current directory. Review these files for error details about failed operations.

For example, errors are logged for incorrect safe or cash drawer configurations and for missing or incorrect references. Warnings are logged for missing but non-required data.

Troubleshooting

If you encounter authentication errors, do the following:

  • Check that your .env credentials are correct.
  • Ensure your user account has the required permissions and scopes.
  • Verify the API endpoint is correct and accessible.

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

  • Confirm all required fields are present.
  • Ensure referenced devices have been created.
  • Check that enum values match for device types, statuses, and other fields.
  • Review the log file for details about failed attempts.