# 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](https://github.com/NebulaTerra/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:

   ```sh title="Clone the repository"
   git clone https://github.com/NebulaTerra/instore-device-cli.git
   cd instore-device-cli
   ```

2. Install dependencies:

   ```sh title="Install dependencies"
   npm install
   ```

3. Make the script executable:

   ```sh title="Make the script executable"
   chmod +x index.js
   ```

4. 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](/instore/use-the-instore-center/store-roles.md) 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](https://github.com/NebulaTerra/instore-device-cli/blob/main/.env.example) as a starting point:

   ```sh title="Copy and edit the sample .env file"
   cp .env.example .env
   nano .env
   ```

5. Test your authentication credentials:

   ```sh title="Test authentication"
   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`](https://github.com/NebulaTerra/instore-device-cli/blob/main/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 [support team](https://support.commercetools.com/). To check supported devices, follow these steps:

1. Log in to the InStore POS.
2. Go to **Manage Devices**.
3. Select a device type or [add a new device](/instore/use-the-instore-center/devices.md).
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 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:

```jsonc title="Device configuration example"
{
  "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
    "alias": "PRINT-LocationID-01", // optional; if omitted, InStore generates an alias during creation
  "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:

```jsonc title="Workstation configuration example"
{
    "workstation_id": "01",                   // required, errors if missing
    "alias": "WORKSTATION-Flagship-01",       // optional; sets the alias on the underlying device for this workstation
    "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
}
```

### Generated alias references

When you use the CLI, InStore creates devices in the following order and automatically assigns them aliases to manage dependencies:

1. Standard devices, such as safes, PEDs, printers, and 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.

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.

In the [example above](/instore/implement-instore/use-instore-device-cli/initial-setup-via-cli.md#configuration-of-workstations), `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](/instore/use-the-instore-center/device-search.md) or by running a [post-job validation](/instore/implement-instore/use-instore-device-cli/initial-setup-via-cli.md#post-run-validation).

### Specified alias reference

For the same `alias` field, you can specify a value in your device or workstation configuration. For workstations, the alias is stored on the underlying device record, not on the workstation record itself. When registering a workstation, you can replace the automatically generated device alias with a custom value that is meaningful to your organization:

```json title="Workstation configuration example"
{
    "name": "iPad Pro",
    "type": "Workstation",
    "alias": "vip01 at store altname",
    "default_PED": "PED-Flagship-01",
    "default_cashdrawer": "CASH-Flagship-01",
    "default_printer": "PRINT-Flagship-01",
    "default_scanner": "SCAN-Flagship-01"
}
```

In this example, `vip01 at store altname` is a custom alias for the workstation device. You can use a meaningful alias value to support workstation-specific processes in your organization. For example:

- Extract the alias identifier and print it on pick tickets so that pickers can identify priority orders.
- Use the alias when a third-party payment services provider (PSP) issues a store identifier that does not match the InStore Store ID.
- Use the alias to meet hardware-specific requirements, such as PSP-specific device information.

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

```sh title="Run the batch command"
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](/instore/implement-instore/use-instore-device-cli/initial-setup-via-cli.md#instore-device-cli-logging).

### Post-run validation

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

1. List all locations:

   ```sh title="List all locations"
   node index.js list-locations
   ```

2. Validate a specific location exists:

   ```sh title="Validate a location exists"
   node index.js validate-location LOCATION_ID
   ```

3. Validate a specific workstation exists:

   ```sh title="Validate a workstation"
   node index.js validate-location LOCATION_ID WORKSTATION_ID
   ```

4. List all devices for a location:

   ```sh title="List devices for a location"
   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/implement-instore/use-instore-device-cli/add-devices-ad-hoc.md).

If your organization has created payment options with the `default` key set to `true`, a new location or workstation can have those payment options automatically associated with it. If there are no default payment options, or if the location or workstation requires special options, you can manually add them. See [Assign payment options to a location](/instore/integration/payments/build-payment-components.md#assign-to-a-location) or [Assign payment options to a workstation](/instore/integration/payments/build-payment-components.md#assign-to-a-workstation).

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

## Related pages

- [Search documentation and API specs](/search.md)