Nine Parsecs from Milwaukee


    4.0.0 • Public • Published

    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:

    export SPHERE_PROJECT_KEY=""
    export SPHERE_CLIENT_ID=""


    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


    npm i sphere-node-cli

    DownloadsWeekly Downloads






    Unpacked Size

    35.3 kB

    Total Files


    Last publish


    • commercetools-admin
    • emmenko
    • hajoeichler
    • yanns
    • tdeekens
    • timonrey
    • vineetkumarkushwaha
    • acbeni
    • markusazer
    • jherey
    • danrleyt
    • jenschude
    • ahmetoz
    • chukwuemeka