Fetching contributors…
Cannot retrieve contributors at this time
187 lines (140 sloc) 6.92 KB

commercetools logo

Node.js CLI

npm Travis Build Status Codecov Coverage Status David Dependencies Status David devDependencies Status

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

Table of Contents


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


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.


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


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:


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:



Docker build

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.


Show help

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

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

docker run \
-v /sample_dir/:/sample_dir/ \
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 \


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.


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": "",
  "title": "SPHERE.IO CLI import schema",
  "type": "object",
  "properties": {
    "<import-type-key>": {
      "type": "array",
      "items": {
        "$ref": ""
  "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.


See Contribution guidelines