Last edit: Mar 12, 2020

The pos-cli is a command line interface that helps you deploy configuration files and assets to your platformOS site. It also allows you to use team collaboration tools like git in your workflow, and it works with cloud storage providers like Amazon AWS S3.


pos-cli requires Node.js in at least latest LTS version to work properly.


Follow our Installing the pos-cli tutorial to install the pos-cli.

Commands and options

All commands should be run in the project root directory (one level above the app directory).


pos-cli [options] [command]


The help [cmd] displays help for the command in [cmd], for example:

pos-cli help data


  • -v, --version: Display the version number
  • -h, --help: Display usage information



Check your code for deprecations, recommendations, errors.

Command Usage Example
audit pos-cli audit pos-cli audit


Export, import or clean data on instance.


  • export <environment>: export Instance data to a JSON file
  • import <environment>: import Instance data from a JSON file
  • clean <environment>: remove all stored data in users, models, etc. Execute with caution, there is no coming back. Works only on staging.
Command Usage Example
data export pos-cli data export <environment> pos-cli data export production
data import pos-cli data import <environment> pos-cli data import production
data clean pos-cli data clean <environment> pos-cli data clean staging


Deploy code to environment. It is recommended to first deploy to staging, test, and only then trigger deploy to production as desribed in the recommended Development Workflow.

Effectively, deploy creates a zip file that contains all your files and sends it to the API. It is then processed in the background. Each zip file is stored by us, to allow you to roll back in case something goes wrong.

Command Usage Example
deploy pos-cli deploy <environment> pos-cli deploy staging

Related topics:


Manage environments.

To add your environment to a config file, run the env add command, and authenticate with your Partner Portal credentials. Configuration for environments is saved in the .marketplace-kit file.

Command Usage Example
env add pos-cli env add <environment> --email <your email> --url <your application url> pos-cli env add staging --email myemail@example.com --url https://example.com
env list pos-cli env list pos-cli env list

Related topics:


GUI for content editor, GraphQL.

To start the http server locally that will serve the GUI use the gui serve command.

GraphiQL IDE: To explore your instance database using GraphQL open http://localhost:3333/gui/graphql in your web browser.

Command Usage Example
gui serve pos-cli gui serve <environment> pos-cli gui serve staging


Initialize required directory structure.

In order to correctly communicate with the platformOS engine and API, your codebase should be organized into a specific directory structure. Use the pos-cli init command to download the directory structure in a zip file, and extract it into the current directory.

Command Usage Example
init pos-cli init pos-cli init


Related topics:


Attach to environment log streams.

Command Usage Example
logs pos-cli logs <environment> pos-cli logs staging


  • -c --config-file <config-file>: config file path (default: ".marketplace-kit")
  • --interval <interval>: time to wait between updates in ms (default: 3000)


Generate, run, or list migrations.


  • generate <environment> <name>: generate new empty migration
  • run <environment> <timestamp>: run migration on environment
  • list <environment>: list migrations and their statuses
Command Usage Example
migrations generate pos-cli migrations generate <environment> <name> pos-cli migrations generate staging add_some_books
migrations run pos-cli migrations run <environment> <timestamp> pos-cli migrations run staging 20180909123423
migrations list pos-cli migrations list <environment> pos-cli migrations list staging

Related topics:


Update environment on file change.

Enables sync mode: it checks what's different between the server and the local environment, and sends files after they have been changed on local. It only sends files that have changed after sync was started. It feels like working on localhost. It is recommended to use sync only for staging environments, as pushing changes immediately to production can be dangerous.

Command Usage Example
sync pos-cli sync <environment> pos-cli sync staging

Related topics:


Manage modules.

Command Usage Example
modules list pos-cli modules list <environment> pos-cli modules list staging
modules remove pos-cli modules remove <environment> <name> pos-cli modules remove staging admin_module
module templates

Templates provide automatic processing for easier module configuration. For example, upon installing a module, it is possible to specify URIs under which pages will be available after the module has been installed. This works both in sync and deploy mode.

Markup is the commonly used ERB/EJS stye: <%= =%> there is no logic supported, the only available filter is & which will unescape the value provided by the user (by default they are all escaped).

Values for variables have to be provided in the root module directory template-values.json, but the location of the configuration file can be set using the TEMPLATE_VALUES_FILE_PATH variable.

For example by executing TEMPLATE_VALUES_FILE_PATH=templates/values.json pos-cli deploy staging file templates/values.json will be used as values for templates.

Directory structure with template-values.json:

    ├── template-values.json
    ├── private
    │   └── graphql
    │       ├── get_models.graphql
    │       └── get_pages.graphql
    └── public
        └── views
            └── pages
                └── admin.liquid


A page with this code:

slug: <%= &desired_location =%>

This is using templates <%= what =%> !

And a template-values.json

  "desired_location": "index",
  "what": "magic"

will turn into this during deploy/sync:

slug: index

This is using templates magic !


Display help for command.

Command Usage Example
help pos-cli help <command> pos-cli help data


We are always happy to help with any questions you may have.