Command Line Interface (CLI) #

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

• Start Kuzzle
• Gracefully shutdown Kuzzle
• Create the first Administrator
• Reset Kuzzle internal data (use with caution!)
• Reset user created indexes (use with caution!)
• Reset users, roles and profiles (use with caution!)

• Load mappings, fixtures, roles, profiles and users

• Clear Kuzzle cache
• Diagnose the Kuzzle installation

The CLI is located in the bin folder of your Kuzzle installation. If you have already created an admin, you will need to provide your login information to the CLI. To get a list of commands and options run the CLI:

./bin/kuzzle

#   Usage: kuzzle [options] [command]
#
#
#   Commands:
#
#   createFirstAdmin [options]          create the first administrator user
#   clearCache [options]                clear internal caches in Redis
#   reset [options]                     reset all users, profiles, roles and documents validation specifications
#   resetSecurity [options]             reset all users, profiles and roles
#   resetDatabase [options]             remove all data stored on Kuzzle
#   shutdown [options]                  gracefully exits after processing remaining requests
#   start [options]                     start a Kuzzle instance
#   dump [options]                      create a dump of current state of kuzzle
#   loadMappings [options] <file>       load database mappings into Kuzzle
#   loadFixtures [options] <file>       load database fixtures into Kuzzle
#   loadSecurities [options] <file>     load roles, profiles and users into Kuzzle
#   encryptSecrets [options] [file]     encrypt a secrets file with the provided key
#   decryptSecrets [options] [file]     decrypt a secrets file with the provided key
#   indexDump [options] <index> <path>  dump an entire index in the specified directory
#   indexRestore [options] <path>       restore the content of a previously dumped index
#
#   Options:
#
#     -h, --help                 output usage information
#     -V, --version              output the version number
#     -p, --port <port>          Kuzzle port number
#     -h, --host <host>          Kuzzle host
#     -U, --username <username>  Admin username
#     -P, --password <password>  Admin password
#     -d, --debug                make errors more verbose
#     -C, --noColors             do not use ANSI coloring

createFirstAdmin #

./bin/kuzzle createFirstAdmin

When Kuzzle runs for the first time, no users are defined and the anonymous user is granted full access rights.

The createFirstAdmin command lets you create an administrator to manage security.

This call the action security#createFirstAdmin

clearCache #

./bin/kuzzle clearCache

Kuzzle uses Redis to store frequently accessed internal data. Use this command if you need to clear this data (cache).

This call the action admin#resetCache

dump #

./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
• the current Kuzzle 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.

This call the action admin#dump

reset #

./bin/kuzzle reset --help

#    Usage: reset [options]
#
#    reset all users, profiles, roles and documents validation specifications
#
#    Options:
#
#      -h, --help             output usage information
#      --noint                non interactive mode

Asynchronously start the following sequence in Kuzzle, in this order:

• Invalidate and delete all users along with their credentials
• Delete all user-defined roles and profiles
• Reset the default roles and profiles to their default values
• Delete all document validation specifications

This action has no impact on Plugin and Document storage.

This call the action admin#resetKuzzleData

resetSecurity #

./bin/kuzzle resetSecurity --help

#    Usage: resetSecurity [options]
#
#    reset all users, profiles and roles
#
#    Options:
#
#      -h, --help             output usage information
#      --noint                non interactive mode

The resetSecurity command deletes all created users, profiles and roles and reset the default roles and profiles : anonymous, admin and default.

This call the action admin#resetSecurity

resetDatabase #

./bin/kuzzle resetDatabase --help

#    Usage: resetDatabase [options]
#
#    delete all data stored on Kuzzle
#
#    Options:
#
#      -h, --help             output usage information
#      --noint                non interactive mode

The resetDatabase delete all indexes created by users. This does not include Kuzzle's internal index.

This call the action admin#resetDatabase

Note: this command has no impact on any plugins stored data, or on any Kuzzle stored documents.

shutdown #

./bin/kuzzle shutdown

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

The shutdown command lets you stop a Kuzzle instance after any remaining requests are processed, ensuring that no unnecessary Service Unavailable errors are returned to connected clients.

This call the action admin#shutdown

start #

./bin/kuzzle start --help

#    Usage: start [options]
#
#    start a Kuzzle instance
#
#    Options:
#
#      -h, --help                        output usage information
#          --fixtures <file>             import data from file
#          --mappings <file>             apply mappings from file
#          --securities <file>           import roles, profiles and users from file
#          --vault-key <vaultKey>        Vault key used to decrypt secrets
#          --secrets-file <secretsFile>  Output file to write decrypted secrets
#          --enable-plugins <plugins>    Enable given plugins (separated with comma)

The start command starts a Kuzzle instance.

Using this command you can also initialize the storage layer mappings, using the mappings --mappings options, and the storage layer documents using the --fixtures option.

--mappings #

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

The input file must be a JSON file with the following structure:

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

Notes:

• The file can contain any number of index and collection configurations.
• Field definitions follow the Elasticsearch mapping format.
• If an index or collection does not exist, it will be created automatically.
• Mappings are loaded sequentially, one index/collection pair at a time. If a failure occurs, Kuzzle immediately interrupts the 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 into the storage layer.

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

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

Notes:

• The file can contain any number of index and collection configurations.
• Each collection contains an array of data to load, just like the bulk:import API.
• If an index or collection does not exist, the load will fail.
• Fixtures are loaded sequentially, one index/collection pair at a time. If a failure occurs, Kuzzle immediately interrupts the sequence.

Example:

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

--securities #

Read roles, profiles and users from a file and loads them into the storage layer.

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

{
  "roles": {
    "role-id": {
      /* role definition */
    }
  },
  "profiles": {
    "profile-id": {
      /* profile definition */
    }
  },
  "users": {
    "user-id": {
      /* user definition */
    }
  }
}

The roles, profiles and users definition follow the same structure as in the body parameter of the API:

• createRole
• createProfile
• createUser

Notes:

• The file can contain any number of roles, profiles and users.
• If a role, profile or user already exists, it will be replaced.
• Fixtures are loaded sequentially, first the roles, then the profiles and finally the users. If a failure occurs, Kuzzle immediately interrupts the sequence.

Example:

{
  "roles": {
    "role-id-1": {
      "controllers": {
        "*": {
          "actions": {
            "*": true
          }
        }
      },
      "role-id-2": {
        "controllers": {
          "*": {
            "actions": {
              "*": true
            }
          }
        }
      }
    },
    "profiles": {
      "profile-id-1": {
        "policies": [
          {
            "roleId": "role-id-1",
            "restrictedTo": []
          }
        ]
      },
      "profile-id-2": {
        "policies": [
          {
            "roleId": "role-id-2",
            "restrictedTo": []
          }
        ]
      }
    },
    "users": {
      "user-id-1": {
        "content": {
          "profileIds": ["profile-id-1"]
        },
        "credentials": {
          "local": {
            "username": "nina",
            "password": "thug"
          }
        }
      },
      "user-id-2": {
        "content": {
          "profileIds": ["profile-id-2"]
        },
        "credentials": {
          "local": {
            "username": "alyx",
            "password": "vance"
          }
        }
      }
    }
  }
}

--enable--plugins #

./bin/kuzzle start --enable-plugins kuzzle-custom-plugin-one,kuzzle-custom-plugin-two

Enable given plugins. If several names are given, they need to be separated with commas. Provided strings must match plugin directory names located in the plugins/available directory.

loadMappings #

./bin/kuzzle loadMappings <file>

# [✔] Mappings have been successfully loaded

The loadMappings command applies mappings directly into the storage layer.

Mappings file example #

{
  "index-name": {
    "collection-name": {
      "properties": {
        "field1": { "type": "keyword" },
        "field2": { "type": "integer" },
        "field...": { "type": "..." }
      }
    }
  }
}

Notes:

• The mapping can contain any number of index and collection configurations.
• Field definitions follow the Elasticsearch mapping format.
• If an index or collection does not exist, it will be created automatically.
• Mappings are loaded sequentially, one index/collection pair at a time. If a failure occurs, Kuzzle immediately interrupts the sequence.

loadFixtures #

./bin/kuzzle loadFixtures <file>

# [✔] Fixtures have been successfully loaded

The loadFixtures command loads fixtures directly into the storage layer.

Fixtures file example #

{
  "index-name": {
    "collection-name": [
      {"create": { "_id": "uniq-id-123456" }},
      {"field": "value", "field2": "value", "field...", "value"}
    ]
  }
}

Notes:

• The fixtures can contain any number of index and collection configurations.
• Each collection contains an array of data to load, just like the bulk:import method.
• If an index or collection does not exist, the load will fail.
• Fixtures are loaded sequentially, one index/collection pair at a time. If a failure occurs, Kuzzle immediately interrupts the sequence.

loadSecurities #

./bin/kuzzle loadSecurities <file>

# [✔] Securities have been successfully loaded

The loadSecurities command loads roles, profiles and users directly into the storage layer.

The roles, profiles and users definition follow the same structure as in the body parameter of the API:

• security:createRole
• security:createProfile
• security:createUser

Securities file example #

{
  "roles": {
    "role-id": {
      /* role definition */
    }
  },
  "profiles": {
    "profile-id": {
      /* profile definition */
    }
  },
  "users": {
    "user-id": {
      /* user definition */
    }
  }
}

Notes:

• The file can contain any number of roles, profiles and users.
• If a role, profile or user already exists, it will be replaced.
• Fixtures are loaded sequentially, first the roles, then the profiles and finally the users. If a failure occurs, Kuzzle immediately interrupts the sequence.

encryptSecrets #

./bin/kuzzle encryptSecrets [file] [options]

# Options:
#       --vault-key <vaultKey>     Vault key used to encrypt secrets
#       --outputFile <outputFile>  Output file to write encrypted secrets
#       --noint                    non interactive mode

Encrypts the provided file with the provided vaultKey.
The vaultKey can be either provided in the command line or in the KUZZLE_VAULT_KEY environment variable.
The file can be provided in the command line or in the default secrets file in <kuzzle dir>/config/secrets.json.

decryptSecrets #

./bin/kuzzle decryptSecrets [file] [options]

# Options:
#       --vault-key <vaultKey>     Vault key used to encrypt secrets
#       --outputFile <outputFile>  Output file to write encrypted secrets
#       --noint                    non interactive mode

Decrypts the provided file with the provided vaultKey.
The vaultKey can be either provided in the command line or in the KUZZLE_VAULT_KEY environment variable.
The file can be provided in the command line, through the KUZZLE_SECRETS_FILE environment variable or in the default secrets file in <kuzzle dir>/config/secrets.enc.json.

indexDump #

./bin/kuzzle indexDump <index> <path> [options]

# Options:
#       --batch-size <batchSize>  Maximum batch size (see limits.documentsFetchCount config)

Dumps the index <index> in the directory <path>.
Each collection is dumped in a separate file in JSON lines format.

The dump directory has the following structure:

<path>
├── <index>--<collection>--data.jsonl
└── <index>--<collection>--data.jsonl

This dump is intended to be loaded with the indexRestore command.

indexRestore #

./bin/kuzzle indexRestore <path> [options]

# Options:
#       --batch-size <batchSize>  Maximum batch size (see limits.documentsWriteCount config)

Restores a previously dumped index from directory <path> into Kuzzle.
The index and destination collections must exist.