Connhex CLI

A command-line interface tool for interacting with Connhex Cloud.

Overview

Connhex CLI allows you to interact with your Connhex Cloud instance directly from your terminal. It provides commands for authentication, configuration management, device provisioning, etc.

Installation

Prerequisites

• Go 1.20 or later

Building from source

1. Clone the repository:

   git clone https://github.com/compiuta-origin/connhex-cli.git
   cd connhex-cli

2. Build the CLI:

   make cli

Getting Started

Note

This guide assumes the connhex-cli binary is globally available (i.e. stored in a directory that has been added to your PATH. Common choices are /usr/local/bin or a custom directory like ~/.bin.)

If this is not your case, navigate to the folder containing the connhex-cli binary. You will then be able to execute all of the commands below by replacing connhex-cli with ./connhex-cli.

Authentication

Before using Connhex CLI, you need to authenticate with your Connhex instance:

connhex-cli login

You will be prompted to enter:

• Your Connhex instance domain
• Email address
• Password

Alternatively, you can provide all parameters in a single command:

connhex-cli login <connhex-instance> <email> <password>

Authentication tokens are stored in ~/.connhex/config.json and are valid for 24 hours.

View Configuration

To check your current configuration:

connhex-cli config

This will display your Connhex instance, authentication token, and other settings.

Device Provisioning

Bulk Device Provisioning

You can provision multiple devices at once using a CSV or JSON file:

connhex-cli provision [--schema=<schema-name>] [--serial-number-field=<field-name>] [--connhex-id-field=<field-name>] <filename>

Flags

• --schema Manufacturing device schema to use (default: devices).

• --serial-number-field Manufacturing device serial number field (default: serial_number).

• --connhex-id-field Manufacturing device Connhex ID field (default: connhex_id).

File Formats

Both CSV and JSON formats are supported.

CSV Format

CSV files must have a header row with the following required columns:

• provision.init_id - Device initialization ID (typically the serial number)
• provision.init_key - Device initialization key

The tenant column is optional; if omitted, devices will be provisioned without a tenant.

Optional provision columns are:

• provision.name - Device name
• provision.model - Device model
• provision.migration_key - Alternative key used by the device to download its configuration if the main key is not available.
• provision.migration_key_quota - The number of times the migration key can be used.

All custom manufacturing data columns use the prefix manufacturing. followed by the field name. These will depend on your Connhex Manufacturing configuration:

• manufacturing.serial_number
• etc.

Example CSV file:

tenant,provision.init_id,provision.init_key,provision.name,manufacturing.serial_number
connhex,SN123456789,f1d1fa88-3da4-46db-b0c4-f003d4594cc8,Sensor 1,SN123456789
connhex,SN123456790,cc8d42e1-063c-48aa-8fd8-1f983b4f2b54,Sensor 2,SN123456790

JSON Format

The JSON file should contain an array of device objects:

[
  {
    "tenant": "connhex",
    "provision": {
      "name": "Sensor 1",
      "init_id": "SN123456789",
      "init_key": "f1d1fa88-3da4-46db-b0c4-f003d4594cc8"
    },
    "manufacturing": {
      "serial_number": "SN123456789"
    }
  }
]

Configuration

The Connhex CLI stores its configuration in ~/.connhex/config.json. This includes:

• connhex_instance: Your Connhex instance domain
• token: Authentication token
• user: User email
• expires_at: Token expiration timestamp

Troubleshooting

I'm getting the following error: error: failed to create entity

Make sure all fields in your devices CSV file are valid: common errors include specifying tenants or models that don't exist.

I'm getting the following error: cmd/main.go:5:2: package slices is not in GOROOT

Make sure your Go version is 1.20+.

License

The project is licensed under the MIT License.