Command Line Interface (CLI)

Kùzu provides a CLI shell through which you can issue Cypher queries or CALL commands to query metadata. See the installation docs for instructions on how to install the CLI and the quick start page for its basic usage.

Start the shell

Kùzu supports on-disk, as well as in-memory databases. The functionality of the CLI is identical for both on-disk and in-memory modes.

On-disk database

You can create an on-disk database in the CLI by specifying a path after the kuzu command in the terminal. This opens the database on-disk, in read-write mode, and the data is persisted to disk after the CLI shell is closed. Note that if the database directory does not exist, it will be created for you.

$ kuzu ./test_db

Opened the database at path: ./test_db in read-write mode.
Enter ":help" for usage hints.
kuzu>

In-memory database

Alternatively, you can create an in-memory database by omitting the path entirely, and just calling kuzu from your terminal:

$ kuzu

Opened the database under in-memory mode.
Enter ":help" for usage hints.
kuzu>

Shell commands

Once you start the shell, you can issue Cypher queries as shown in the get started section. List all available shell commands by running ./kuzu -h.

$ kuzu -h
  kuzu [databasePath] {OPTIONS}

    KuzuDB Shell

  OPTIONS:

      databasePath                      Database path.
      -h, --help                        Display this help menu
      -d, --default_bp_size,
      --defaultbpsize                   Size of buffer pool for default and
                                        large page sizes in megabytes
      --no_compression, --nocompression Disable compression
      -r, --read_only, --readonly       Open database at read-only mode.
      -p, --path_history                Path to directory for shell history
      -v, --version                     Display current database version
      -m, --mode                        Set the output mode of the shell
      -s, --no_stats, --nostats         Disable query stats
      "--" can be used to terminate flag options and force all following
      arguments to be treated as positional options

Note on memory usage

By default, Kùzu’s CLI is launched with a maximum buffer pool size of 80% of the available memory. If you want to launch the Kùzu CLI with a different buffer pool size, you can do so by setting the --defaultbpsize or -d flag to the desired value in megabytes.

To limit the buffer pool size to use just 4GB of memory, you can use the following command:

kuzu --defaultbpsize 4096

:help

Show built-in command list within the Kùzu shell.

kuzu> :help
    :help     get command list
    :clear     clear shell
    :quit     exit from shell
    :max_rows [max_rows]     set maximum number of rows for display (default: 20)
    :max_width [max_width]     set maximum width in characters for display
    :mode [mode]     set output mode (default: box)
    :stats [on|off]     toggle query stats on or off
    :multiline     set multiline mode (default)
    :singleline     set singleline mode
    :highlight [on|off]     toggle syntax highlighting on or off
    :render_errors [on|off]     toggle error highlighting on or off

    Note: you can change and see several system configurations, such as num-threads,
          timeout, and progress_bar using Cypher CALL statements.
          e.g. CALL THREADS=5; or CALL current_setting('threads') return *;
          See: https://docs.kuzudb.com/cypher/configuration

:clear

Clear shell. Alternatively, you can use Ctrl + L to clear the shell.

:quit

Exit from shell. Alternatively, you can use Ctrl + D to exit the shell.

:max_rows [max_rows]

Set maximum number of rows for display. 0 defaults to 20.

:max_width [max_width]

Set maximum width in characters for display. Defaults to terminal width if unable to display first and last columns.

:mode [mode]

Set output mode. The default mode is box. See the output modes section below for more details.

:stats [on|off]

Toggle query statistics on or off. The default is on. Query statistics include the number of tuples, columns, and execution time.

:multiline

Set multiline editing mode. This is the default editing mode. In multiline editing mode, you can write queries that span multiple lines. In this mode, you are able to go back to previous lines and edit them. Comments and newlines will stay when saved into history when using this mode.

kuzu> :multiline
Multi line mode enabled
kuzu> CREATE NODE TABLE
    · Person(name STRING,
    · age INT64,
    ‣ PRIMARY KEY (name) // a comment here too
    · );

The ‣ symbol indicates the current line.

:singleline

Set singleline editing mode. In singleline editing mode, you can only write queries on a single line. If your query spans multiple lines, you will not be able to go back to previous lines and edit them. Single-line comments and newlines will not be saved into history when using this mode.

kuzu> :singleline
Single line mode enabled
kuzu> CREATE NODE TABLE
..> Person(name STRING,
..> age INT64,
..> PRIMARY KEY (name) // a comment here too
..> );

:highlight [on|off]

Toggle syntax highlighting on or off. The default is on. When enabled, the shell will highlight Cypher keywords, constants and literals, syntax errors, and comments. Error highlighting and multiline comment highlighting are not available in singleline mode.

:render_errors [on|off]

Toggle error highlighting on or off. The default is on. When enabled, the shell will highlight syntax errors in red. In particular, mismatched brackets and unclosed quotes will be highlighted. Error highlighting is not available in singleline mode.

Interrupt shell

To interrupt a running query, use Ctrl + C in CLI. Note: We currently don’t support interrupting a running COPY statement.

Non-interactive usage

You can also read and process a file in non-interactive mode via the CLI. Consider that you have the following DDL file:

schema.cypher

CREATE NODE TABLE Person (name STRING, age INT64, PRIMARY KEY(name));
COPY Person FROM 'person.csv';

Pipe the file content to the CLI as follows:

./kuzu testdb < schema.cypher

Opened the database at path: ./test_db in read-write mode.
Enter ":help" for usage hints.
┌────────────────────────────────┐
│ result                         │
│ STRING                         │
├────────────────────────────────┤
│ Table Person has been created. │
└────────────────────────────────┘
(1 tuple)
(1 column)
Time: 0.04ms (compiling), 0.82ms (executing)
┌────────────────────────────────────────────────┐
│ result                                         │
│ STRING                                         │
├────────────────────────────────────────────────┤
│ 4 tuples have been copied to the Person table. │
└────────────────────────────────────────────────┘
(1 tuple)
(1 column)
Time: 0.09ms (compiling), 11.75ms (executing)

Query progress

For queries that might take a significant amount of time to execute, a progress bar can be enabled that displays the number of pipelines that have been executed (each query is broken down into one or more pipelines), as well as the percentage of the data processed in a pipeline. This gives an estimate for how much of a pipeline has executed.

The progress bar is not enabled by default. To enable the progress bar, use the following command:

CALL progress_bar=true;

To further configure the progress bar, see the configuration section.

Output modes

The :mode [mode] command allows you to change the appearance of the tables returned by queries. To view the available modes, use the :mode command without any arguments:

kuzu> :mode
Available output modes:
    box (default):    Tables using unicode box-drawing characters
    column:    Output in columns
    csv:    Comma-separated values
    html:    HTML table
    json:    Results in a JSON array
    jsonlines:    Results in a NDJSON format
    latex:    LaTeX tabular environment code
    line:    One value per line
    list:    Values delimited by "|"
    markdown:    Markdown table
    table:    Tables using ASCII characters
    tsv:    Tab-separated values
    trash:    No output

To change the output mode, use the :mode command followed by the desired mode:

kuzu> :mode json
mode set as json
kuzu> CREATE NODE TABLE Person (name STRING, age INT64, PRIMARY KEY(name));
[{"result":"Table Person has been created."}]

The :max_rows and :max_width commands can be used to control the number of rows and the width of the box, column, table, and markdown output modes.

Multi-line Cypher statements

The CLI supports queries written in multiple lines. If a semicolon is omitted, hitting enter will allow users to continue the query in a newline instead of executing it.

kuzu> MATCH (a:person)
    ‣ RETURN a.id;