The Horizon CLI

The hz command line tool’s primary function is to start a standalone Horizon server. It also provides utilities for initializing a new Horizon project, creating a self-signed SSL certificate, and other tasks.

Commands

init

Initialize a new Horizon project. hz init with no argument will initialize a project in the current directory; hz init <directory> will initialize a project in the specified directory, creating the directory if necessary. The project will be given the name of the specified directory (the current directory if no argument is given).

serve

The hz serve <project path> command starts a Horizon server for the given Horizon project. Once started, it serves HTTP(S) requests for your application on the configured port.

Every Horizon server requires a RethinkDB server to connect to. Use the --connect <RethinkDB host> option to connect to an existing RethinkDB server, or use --start-rethinkdb to automatically start a local RethinkDB server. (Note that the --dev option for development mode includes --start-rethinkdb by default.)

Note that if you are using a database from a Horizon 1.x application, the serve command will exit with an error. Use hz migrate to upgrade your database in place.

Command-line options

hz serve supports the following command-line options:

General options

Network options

The following options provide alternatives to specifying these values in the --connect string:

Authentication options

Development options

Development mode

In development mode (hz serve --dev), the following flags are enabled by default:

Development mode makes it easy to run a local Horizon instance during application development. Because permission checking is disabled and collections and indexes get automatically created, new application code can be tested without additional configuration.

Development mode should never be enabled on a production server that is publicly accessible. An attacker can exploit a development server by sending unintended requests. These requests can be used to read and/or modify arbitrary data stored for your Horizon application, or can be used to exhaust the resources of your server.

create-cert

Create a private and public TLS certificate pair for development. Running this will create two files, horizon-cert.pem and horizon-key.pem. These can be specified as options to hz serve or placed in the configuration file.

Note that the certificate created by create-cert uses no local identity information; the data is completely random. If you need to use an existing certificate or credentials, you’ll have to create the certificate on your own using openssl or a similar tool.

schema save

Save the currently defined Horizon schema, including validation rules, collection and index specifications, as a TOML file. For an example of this command in practice, read the section on “Configuring rules” in Permissions and schema enforcement.

Run hz schema save -h for details on options.

If you use the default schema filename (.hz/schema.toml), existing schema files will be preserved, renamed to schema.toml_ with a datestamp appended.

schema apply

Load a previously-extracted schema into a Horizon cluster. Run hz schema apply -h for details on options.

While the schema format changed with Horizon 2.0, schema apply will read pre-2.0 files. (Use schema save to rewrite them in the current format.)

migrate

Migrate a Horizon database from the 1.x to 2.x internal format. This command must be used on databases created with Horizon 1.x applications; Horizon will exit with an error if the serve command is executed with an old format database.

make-token

Manually create a JSON Web Token for a user, allowing user bootstrapping. This is necessary to log in as the Horizon admin user the first time. Simply pass the user ID value to make-token as the argument:

hz make-token [user-id]

The JWT will be printed to the console.

For more details, read “Making an admin auth token” in Permissions and schema enforcement.