Skip to content
CLI tool to build Koop projects
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.
scripts F/serve command for all plugin types (#34) Jul 8, 2019
src update dependencies and fix small bugs Jul 8, 2019
test update dependencies and fix small bugs Jul 8, 2019
.gitignore S/prepare for v0.3.0 release (#25) Apr 17, 2019
.travis.yml update changelog Jul 8, 2019
LICENSE update package info (#7) Jan 28, 2019 F/serve command for all plugin types (#34) Jul 8, 2019
package-lock.json 0.5.0 Jul 8, 2019
package.json 0.5.0 Jul 8, 2019


npm package Build Status

An easy-to-use CLI tool to quickly build Koop applications and plugins


  • follow Koop specification
  • minimal project templates
  • full development cycle support
  • console commands + Node.js APIs
  • cross-platform


Use npm

npm install -g @koopjs/cli

Use yarn

yarn global add @koopjs/cli

Once installed the koop command is available at the console.


Create a new Koop application with the name my-koop-app

# create a project folder and initialize it
koop new app my-koop-app

# cd in the folder
cd my-koop-app

Add a provider @koopjs/filesystem-s3 from npm

# install the provider and register it to the koop app
koop add provider @koopjs/filesystem-s3

Add a custom provider that connects to a local database

# add boilerplate provider files at src/providers/local-db and register it to
# the koop app (though you still need to implement the provider)
koop add provider providers/local-db --local

Test out your work

# run the koop server
koop serve


koop <command>

  koop new <type> <name>  create a new koop project
  koop add <type> <name>  add a new plugin to the current app
  koop test               run tests in the current project
  koop serve [path]       run a Koop server for the current project

  --quiet    supress all console messages except errors
                                                      [boolean] [default: false]


The new command creates a new Koop project from the template at the current location.

koop new <type> <name>

  type  project type
                         [string] [choices: "app", "provider", "auth", "output"]
  name  project name                                                    [string]

  --config        specify the project configuration in JSON             [string]
  --skip-install  skip dependence installation        [boolean] [default: false]
  --skip-git      do not initialize Git               [boolean] [default: false]

For more details on the project templates, please take a look at the Koop specification and samples.


The add command adds a Koop plugin to the current Koop app.

koop add <type> <name>

  type  plugin type    [string] [choices: "output", "provider", "cache", "auth"]
  name  plugin name                                                     [string]

Provider Options:
  --route-prefix  add a prefix to all of a registered routes            [string]

  --local         add a plugin from a local path                        [string]
  --config        specify the plugin configuration in JSON              [string]
  --add-to-root   add the given configuration to the app root configuration
                                                      [boolean] [default: false]
  --skip-install  skip plugin installation            [boolean] [default: false]


The serve command starts a test server for the current project.

For Koop apps, the command runs the app directly.

For Koop plugins, the command creates a Koop server that includes the plugin and a simple GeoJSON provider named dev-provider (source). This GeoJSON provider is only registered if the current Koop project is not a provider project. It makes sure the Koop server has an output (geoservices by default) and a provider. When the GeoJSON provider is used, the data file path is required to provide test data (must be *.geojson).

If a more customized test server is needed, you can provide your test server file path to the command.

koop serve [path]

run a koop server for the current project

  path  server file path                                                [string]

  --port, -p  port number of the server                                 [number]
  --data      path to a GeoJSON data file for testing Koop plugin       [string]


The test command run tests in the current koop project.

koop test


This tool can be also used as a library.

const cli = require('@koopjs/cli')

// create a koop app project at /Documents'/Documents', 'app', 'my-app', {
  config: {
    port: 8080

new(cwd, type, name, [options])

Create a Koop project at the given directory.

  • cwd: current work directory
  • type: project type
  • name: project name

Return a promise.

add(cwd, type, name, [options])

Add a plugin to the given Koop app

  • cwd: Koop app directory
  • type: project type
  • name: Koop plugin name

Return a promise.

You can’t perform that action at this time.