Running Crash

This document covers the basics of running Crash from the command-line.


For help using Crash for the first time, check out Getting started.

Table of contents

Command-line options

The crash executable supports multiple command-line options:




Print the help message and exit.


Print debug information to STDOUT.


Print the Crash version and exit.


Print system and cluster information.

--username <USERNAME>

Authenticate as <USERNAME>.


Force a password prompt.

If not set, a password prompt happens when required.

--command <STATEMENT>

Execute the <STATEMENT> and exit.

--hosts <HOSTS>

Connect to <HOSTS>.

<HOSTS> can be a single host, or it can be a space separated list of hosts.

If multiple hosts are specified, Crash will attempt to connect to all of them. The command will succeed if at least one connection is successful.

--timeout <TIMEOUT>

Configure network timeout in “<connect_sec>” or “<connect_sec>,<read_sec>” format.

The default value is “5,-1”, configuring a connect timeout of five seconds with infinite read timeout.

--history <FILENAME>

Use <FILENAME> as a history file.

Defaults to the crash_history file in the user configuration directory.

--config <FILENAME>

Use <FILENAME> as a configuration file.

Defaults to the crash.cfg file in the user configuration directory.

--format <FORMAT>

The output <FORMAT> of the SQL response.

Available formats are: tabular, raw, json, json_row, csv and mixed.

--schema <SCHEMA>

The default schema that should be used for statements.

-A ,

Disable SQL keywords autocompletion.

Autocompletion requires a minimum terminal height of eight lines due to size of the dropdown overlay for suggestions. Disabling autocompletion removes this limitation.

-a ,

Enable automatic capitalization of SQL keywords while typing.

This feature is experimental and may be removed in future versions.


Force the verification of the server SSL certificate.

--cert-file <FILENAME>

Use <FILENAME> as the client certificate file.

--key-file <FILENAME>

Use <FILENAME> as the client certificate key file.

--ca-cert-file <FILENAME>

Use <FILENAME> as the certificate authority (CA) certificate file (used to verify the server certificate).


Here’s an example command:

sh$ crash --hosts \
        -c "SELECT * FROM sys.nodes" \
        --format json \
    > output.json

This command will:

  • Run crash, which will:

    • Attempt to connect to and

    • Execute SELECT * FROM sys.nodes

    • Print the results as JSON

  • Redirect output to the output.json file


Instead of redirecting to a file, you can pipe into a tool like jq for for further processing of the response.

We can modify this command to use SSL, like so:

sh$ crash --hosts \
        --verify-ssl true \
        --cert-file ~/.certs/client.crt \
        --key-file ~/.certs/client.key \
        --ca-cert-file ~/.certs/server-ca.crt \
        -c "SELECT * FROM sys.nodes" \
        --format json \
    > output.json

Here, we’re using:

  • ~/.certs/client.crt as the client certificate

  • ~/.certs/client.key as the client certificate key

  • ~/.certs/server-ca.crt as the server CA certificate

User configuration directory

The crash executable looks for its configuration file and history file in the appropriate user configuration directory for your operating system.

For Linux, that is:


For macOS, it is:

~/Library/Application Support/Crate

And for Microsoft Windows, it is:


Environment variables

The crash executable will take configuration from the environment.

At the moment, only one environment variable is supported.


The password to be used if password authentication is necessary.


Storing passwords in the environment is not always a good idea from a security perspective.

You can set CRATEPW like so:


Here, <PASSWORD> should be replaced with the password you want to use.

For the duration of your current session, invokations of crash will use this password when needed (unless you force a password prompt with --password or -W).

Status messages

When used interactively, Crash will print a status message after every successfully executed query.


When used non-interactively, these messages are omitted.

Examples of non-interactive use include: executing crash in a shell script, redirecting output to a file, or piping output into a another command

If the query alters rows, the status message looks like this:

<STATEMENT>, <NUMBER> row(s) affected (<DURATION> sec)

If the query returns rows, the message looks like this:

<STATEMENT> <NUMBER> row(s) in set (<DURATION> sec)

In both instances:

  • <STATEMENT> is the query keyword (e.g. CREATE, INSERT, UPDATE, DELETE, SELECT, and so on)

  • <NUMBER> is the number of rows (-1 for queries that do not affect any rows or if the row count is unknown)

  • <DURATION> is the total number of seconds the query took to execute on the cluster

Using a pager program

You can use applications like the jless JSON exploration tool or the pspg pager program to view the result sets, by utilizing the \pager command.

Crash Pager


Use those instructions to drill down into the results of your query by exploring it using jless, like outlined within the screencast above:

cr> \pager jless
cr> \format json
cr> SELECT * FROM sys.nodes;