CLI tools

CrateDB ships with command-line interface (CLI) tools (also referred to as executables) in the bin directory.

If your working directory is CRATE_HOME, you can run an executable like this:

sh$ bin/crate

Otherwise, you can run:

sh$ <PATH_TO_CRATE_HOME>/bin/crate

Here, replace <PATH_TO_CRATE_HOME> with a path to CRATE_HOME.

Alternatively, if the CrateDB bin directory is on your PATH, you can run an executable directly:

sh$ crate

Table of contents


The crate executable runs the CrateDB daemon.

See also

This section is a low-level command reference. For help installing CrateDB for the first time, check out the CrateDB installation tutorial. Alternatively, consult the deployment guide for help running CrateDB in production.


sh$ bin/crate [-dhvCDX] [-p <PID_FILE>]


Option Description
-d Start the daemon in the background
-h Print usage information
-p <PID_FILE> Log the PID to a file
-v Print version information
-C Set a CrateDB configuration value (overrides configuration file)
-D Set a Java system property value
-X Set a nonstandard java option

Signal handling

The CrateDB process can handle the following signals.

Signal Description
TERM Terminates the process
INT Terminates the process


The TERM signal stops CrateDB immediately. As a result, pending requests may fail. To ensure that CrateDB finishes handling pending requests before the node is stopped, you can, instead, perform a graceful stop with the DECOMMISSION statement.


The simplest way to start a CrateDB instance is to invoke crate without parameters:

sh$ bin/crate

This command starts the process in the foreground.

You can also start CrateDB in the background with the -d option. When doing this, it’s helpful to write the process ID (PID) to a PID file with the -p option. So, in combination:

sh$ bin/crate -d -p

To stop the process, send a TERM signal using the PID file, like so:

sh$ kill -TERM `cat`


The crate-node executable is a tool that can help you:

See also

This section is a low-level command reference. For help using crate-node, consult the troubleshooting guide.


sh$ bin/crate-node repurpose|unsafe-bootstrap|detach-cluster
[--ordinal <INT>] [-E <KV_PAIR>]
[-h, --help] ([-s, --silent] | [-v, --verbose])


Command Description
repurpose Clean up any unnecessary data on disk after changing the role of a node.
unsafe-bootstrap Force the election of a master and create a new cluster in the event of losing the majority of master-eligible nodes.
detach-cluster Detach a node from a cluster so that it can join a new one.


Option Description
--ordinal <INT> Specify which node to target if there is more than one node sharing a data path
-E <KV_PAIR> Configures a setting using a key-value (KV) pair
-h, --help Return all of the command parameters
-s, --silent Show minimal output
-v, --verbose Shows verbose output


How helpful was this page?