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.

Ask about this Page

Copy for LLM

View as Markdown

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:

Clone the repository:
Clone the repositoryshell
```
git clone https://github.com/NebulaTerra/instore-device-cli.git
cd instore-device-cli
```
Install dependencies:
Install dependenciesshell
```
npm install
```
Make the script executable:
Make the script executableshell
```
chmod +x index.js
```

Create a .env file with the following variables:

Variable	Description
`API_BASE_URL`	Base URL of your REST API. Default: `http://localhost:5000`.
`USER_ID`	User ID for authentication.
`TENANT_ID`	Tenant ID for authentication.
`CONNECTION_KEY`	Environment connection key for authentication.
`SCOPES`	(Optional) Comma-separated list of scopes corresponding to Store Role permissions for the CLI when accessing the InStore API. If not specified, default scope is `devicemanagement`.
`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

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:

Log in to the InStore colleague app.
Go to Manage Devices.
Select a device type or add a new device.
In the Supported Devices field, view the available options.
Enter the device name in the name field of your configuration file. Use the exact spelling from the Supported Devices field.

Configuration of devices

Most retail locations include the following device types:

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

These device types share a set of basic attributes:

{
  "name": "Epson TM88VI",         // required, must match Supported Devices drop-down in Manage Devices
  "type": "Printer",              // required, options are Safe, Printer, CashDrawer, Scanner, PED, Workstation
  "description": "Front printer", // optional, defaults to empty string
  "status": "Active",             // required, defaults to Inactive
  "brand": "Epson",               // required, defaults to empty string
  "model": "TM88VI",              // required, defaults to empty string
  "shared": "true"                // required, defaults to false
  "width": 48,                    // optional (number)
  "serial_number": "12345679",    // optional (string)
  "managing_agent": "Stripe",     // optional (string), options are "Stripe", "Adyen", "Custom"
  "proxy_device_id": "64cbd5e25ad61ab364095272",    // optional (string)
  "proxy_address": "http://proxy.example.com:1234", // optional (string)
  "registration_code": "REG-VF-12345",              // optional (string)
  "ip_address": "192.168.1.101",                    // optional (string)
}

Presence of device data is validated during batch processing if the .json file specifies that devices are to be created.

Configuration of workstations

Workstations are created along with other devices, but they are a special case. They have the following additional attributes that require your attention:

{
    "workstation_id": "01",                   // required, errors if missing
    "default_PED": "PED-Flagship-01",         // optional for retailer, can be none or the device id
    "default_cashdrawer": "CASH-Flagship-01", // optional for retailer, can be none or the device id
    "default_printer": "PRINT-Flagship-01",   // optional for retailer, can be none or the device id
    "default_scanner": "SCAN-Flagship-01",    // optional for retailer, can be none or the device id
    "mobility": "Fixed",                      // required, options are Fixed or Mobile
    "onscreen_keypad": true                   // required, default is true
}

Alias references

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

Standard devices, such as safes, PEDs, printers, and scanners.
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.
Workstations are created last, as they reference other device types.

You can use generated alias values to reference devices in your configuration. These aliases stand in for the actual device IDs until the devices are created. Otherwise you would need to manually look up and enter device IDs after the fact, which is impractical for bulk operations.

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.

In the example above, PED-Flagship-01 is a locally unique alias that temporarily stands in for the device ID until the device is created. You can confirm the device ID later in the InStore Center or by running a post-job validation.

Run and validate the configuration file

Pre-run validation

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.

Post-run validation

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

List all locations:
List all locationsshell
```
node index.js list-locations
```
Validate a specific location exists:
Validate a location existsshell
```
node index.js validate-location LOCATION_ID
```
Validate a specific workstation exists:
Validate a workstationshell
```
node index.js validate-location LOCATION_ID WORKSTATION_ID
```
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.

Set up locations and devices using the InStore device CLI

InStore device CLI overview.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Prerequisites.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Set up your local repository.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Create the configuration file.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Configuration of devices.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Configuration of workstations.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Alias references.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Alias references.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Run and validate the configuration file.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Pre-run validation.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Post-run validation.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

InStore device CLI logging.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Troubleshooting.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

InStore device CLI overview

Prerequisites

Set up your local repository

Create the configuration file

Configuration of devices

Configuration of workstations

Alias references

Alias references

Run and validate the configuration file

Pre-run validation

Post-run validation

InStore device CLI logging

Troubleshooting