Command Line Interface

Kuzzle ships with a Command line interface which enables you to:

  • start a Kuzzle Core,
  • shutdown a Kuzzle Core gracefully
  • create the first administrator user
  • reset Kuzzle internal data (use with caution !)
  • clear Kuzzle's cached data
  • produce a diagnostic dump of a Kuzzle Core current state
#!/bin/bash

./bin/kuzzle

#   Usage: kuzzle [options] [command]
#
#
#   Commands:
#
#     createFirstAdmin   create the first administrator user
#     clearCache         clear internal caches in Redis
#     reset [options]    delete Kuzzle configuration and users from database
#     shutdown           gracefully exits after processing remaining requests
#     start [options]    start a Kuzzle instance
#     dump               create a dump of current state of kuzzle
#
#   Options:
#
#     -h, --help      output usage information
#     -V, --version   output the version number
#     -d, --debug     make errors more verbose
#     -C, --noColors  do not use ANSI coloring

createFirstAdmin

#!/bin/bash

./bin/kuzzle createFirstAdmin

When Kuzzle runs for the first time, no users are defined and the anonymous user is granted with super-admin rights.

The createFirstAdmin command lets you define an administrator user and set your own permissions.


clearCache

#!/bin/bash

./bin/kuzzle clearCache

Kuzzle relies on the Redis service to store frequently accessed internal data. If you need to restart Kuzzle with a fresh cache, this command can come in hand.


dump

#!/bin/bash

./bin/kuzzle dump

# [ℹ] Creating dump file...
# [✔] Done!
#
# [ℹ] Dump has been successfully generated in "dump/<date>-<time>-cli" folder
# [ℹ] You can send the folder to the kuzzle core team at support@kuzzle.io

The dump command creates a snapshot of the state of Kuzzle, including:

  • a coredump of Kuzzle Core
  • the current Kuzzle Core instance configuration
  • server logs
  • Node.js binary & properties
  • a list of OS properties
  • plugins configuration,
  • usage statistics of the dumped instance

The generated directory can be used to feed a crash report to the support team if you own a Kuzzle License.


reset

#!/bin/bash

./bin/kuzzle reset --help

#    Usage: reset [options]
#
#    delete Kuzzle configuration and users from database
#
#    Options:
#
#      -h, --help             output usage information
#      --noint                non interactive mode

The reset command deletes all currently set configurations and users from the database.

Only Kuzzle internal data are cleaned up: this command has no impact over plugins stored data, or stored documents.


shutdown

#!/bin/bash

./bin/kuzzle shutdown

# [ℹ] Shutting down...
# [✔] Done!

The shutdown command allows to stop a Kuzzle Core instance after remaining requests are processed, ensuring that no unnecessary Service Unavailable errors are forwarded to clients.


start

#!/bin/bash

./bin/kuzzle start --help

#    Usage: start [options]
#
#    start a Kuzzle instance
#
#    Options:
#
#      -h, --help                 output usage information
#      -p, --port <port>          Kuzzle port number
#          --fixtures <file>      import data from file
#          --mappings <file>      apply mappings from file

The start command starts a Kuzzle Core instance in the foreground.

This command also allows to initialize the storage layer with preset mappings (--mappings) and documents (--fixtures).

--mappings

Loads mappings from a file and applies them to the storage layer.

The file must be a JSON file of the following structure:

{
  "index": {
    "collection": {
      "properties": {
        "field1": {},
        "field2": {},
        "field...": {}
      }
    },
  }
}

Notes:

  • the file may contain as many index and collection descriptions as necessary
  • field definitions follow the Elasticsearch mapping format
  • Non-existing indexes or collections are automatically created
  • Mappings are loaded sequentially, one index/collection pair at a time. If a failure occurs, Kuzzle immediately interrupts its starting sequence
  • Mappings can be replayed across multiple Kuzzle start sequences, as long as they do not change in-between

Example:

{
  "foo": {
    "bar": {
      "properties": {
        "foobar": {"type": "keyword"},
        "barfoo": {"type": "integer"}
      }
    },
    "baz": {
      "properties": {
        "created": {"type": "date", "format": "strict_date_optional_time||epoch_millis"},
        "other": {"type": "text"}
      }
    }
  }
}

--fixtures

Reads documents from a file and loads them in the storage layer.

The file must be a JSON file, of the following format:

{
  "index": {
    "collection": [
      {"<command>": {}},
      {"field": "value", "field2": "value", "field...", "value"}
    ]
  }
}

Notes:

  • the file may contain as many index and collection descriptions as necessary
  • each collection description is an array containing data to load, following the bulk:import API
  • Non-existing indexes or collections will throw errors
  • Fixtures are loaded sequentially, one index/collection pair at a time. If a failure occurs, Kuzzle immediately interrupts its starting sequence

Example:

{
  "foo": {
    "bar": [
      {"index": {}},
      {"field": "foo", "another_field": 42},
      {"index": {}},
      {"field": "foo", "another_field": 42}
    ],
    "baz": [
      {"index": {}},
      {"bar": "baz", "qux": ["q", "u", "x"]}
    ]
  }
}