🚨 Non-maintainable 🚨

Starting January 1, 2025, we will no longer provide maintenance or updates for the CLI ImpEx tools. After this date, this tool will no longer receive bug fixes, security patches, or new features.

Node.js CLI

The next generation Command-Line-Interface for SPHERE.IO.

Table of Contents

• Features
• Requirements
• Usage
• Credentials
• Docker
  • Examples
• Commands
  • sphere-import
• Contributing

Features

• import of stock, product, price, category, discount, order, customer, productType, discountCode, state, customObject
• Docker support
• Custom plugin

Requirements

Make sure you have installed all of the following prerequisites on your development machine:

• Git - Download & Install Git. MacOS and Linux machines typically have this already installed.
• Node.js - Download & Install Node.js and the npm package manager. Make sure to get the latest active LTS version. You could also use a Node.js version manager such as n or nvm.

If you were using the old ruby CLI make sure to uninstall it first.

Usage

$ npm install -g sphere-node-cli

# show general help
$ sphere -h

# show help for a command (e.g.: import)
$ sphere help <cmd>

The CLI is still under development but already provides a bunch of commands.
The idea behind it is to operate as a proxy for the different libraries that are used underneath. For example the import command will stream chunks from a given JSON file and pass them to the related library that will handled the rest.

Credentials

The CLI has a lookup mechanism to load SPHERE.IO project credentials.
If you specify a -p, --project option, the CLI will try to load the credentials for that project from the following locations:

./.sphere-project-credentials
./.sphere-project-credentials.json
~/.sphere-project-credentials
~/.sphere-project-credentials.json
/etc/sphere-project-credentials
/etc/sphere-project-credentials.json

There are 2 supported formats: csv and json.

• csv: project_key:client_id:client_secret
• json: { "project_key": { "client_id": "", "client_secret": "" } }

If no -p, --project option is provided, the CLI tries to read the credentials from ENV variables:

export SPHERE_PROJECT_KEY=""
export SPHERE_CLIENT_ID=""
export SPHERE_CLIENT_SECRET=""

Docker

You need to have a working docker client! The Docker Toolbox is an installer to quickly and easily install and setup a Docker environment on your computer. Available for both Windows and Mac, the Toolbox installs Docker Client, Machine, Compose, Kitematic and VirtualBox.

Examples

Show help

docker run \
sphereio/sphere-node-cli -h

Import a product (host folder /sample_dir/ mounted as docker volume)

docker run \
-e SPHERE_PROJECT_KEY=<KEY>
-e SPHERE_CLIENT_ID=<ID>
-e SPHERE_CLIENT_SECRET=<SECRET>
-v /sample_dir/:/sample_dir/ \
sphereio/sphere-node-cli
import -p my-project-key -t product -f /sample_dir/products.json'

You can also set an alias for repeated calls:

alias sphere='docker run \
-v /etc/sphere-project-credentials.json:/etc/sphere-project-credentials.json \
sphereio/sphere-node-cli'

Commands

The CLI has git-like sub-commands which can be invoked as sphere <cmd>.

Current available commands:

• import (stock, product, price, category, discount, order, customer, productType, discountCode, state, customObject)

Commands expects at least a -t, --type option which may vary for each command.

sphere-import

Imports a resource type by streaming the input JSON file.

$ sphere import -p my-project-key -t product \
  -f sample_dir/products.json \
  -c '{"errorDir": "./productErrors"}'

The input must be a valid JSON following a specific schema (import-type-key is the plural form of the type option, e.g.: products, stocks, etc.).

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "SPHERE.IO CLI import schema",
  "type": "object",
  "properties": {
    "<import-type-key>": {
      "type": "array",
      "items": {
        "$ref": "https://github.com/sphereio/sphere-json-schemas/tree/master/schema"
      }
    }
  },
  "additionalProperties": false,
  "required": ["<import-type-key>"]
}

If you don't provide a file to read from, the CLI listens from stdin so you can i.e. pipe in something.

Each import type might have / expect some extra specific configuration. In that case you have to refer to the related documentation.

• Product import
• Product Type import
• Price import
• Category import
• Product Discount import
• Customer import
• Stock import
• Order import
• Discount Code import
• State import
• Custom Object import

Contributing

See Contribution guidelines