Cypher Shell

About Cypher Shell CLI

Cypher Shell is a command-line tool used to run queries and perform administrative tasks against a Neo4j instance. By default, the shell is interactive, but you can also use it for scripting by passing Cypher directly on the command line or by piping a file with Cypher statements (requires PowerShell on Windows). It communicates via the Bolt protocol.

Cypher Shell is located in the bin directory if installed as part of the product. Alternatively, you can download it from Neo4j Deployment Center and install it separately.

Syntax

The syntax for running Cypher Shell is:

 cypher-shell [-h] [-a ADDRESS]
              [-u USERNAME] [--impersonate IMPERSONATE]
              [-p PASSWORD] [--encryption {true,false,default}]
              [-d DATABASE] [--access-mode {read,write}]
              [--format {auto,verbose,plain}]
              [-P PARAM] [--non-interactive] [--sample-rows SAMPLE-ROWS]
              [--wrap {true,false}] [-v] [--driver-version]
              [-f FILE] [--change-password] [--log [LOG-FILE]]
              [--history HISTORY-BEHAVIOUR]
              [--notifications] [--fail-fast | --fail-at-end]
              [--idle-timeout IDLE-TIMEOUT]
              [cypher]

Positional arguments

Option Description

cypher

An optional string of Cypher to execute and then exit.

Named arguments

Option Description Default

-h, --help

Show this help message and exit.

--fail-fast

Exit and report failure on the first error when reading from a file (this is the default behavior).

--fail-at-end

Exit and report failures at the end of the input when reading from a file.

--enable-autocompletions

Whether to enable Cypher autocompletions inside the CLI, which are disabled by default.

--format {auto,verbose,plain}

Desired output format. Displays the results in tabular format if you use the shell interactively and with minimal formatting if you use it for scripting.
verbose displays results in a tabular format and prints statistics.
plain displays data with minimal formatting.

auto

-P PARAM, --param PARAM

Add a parameter to this session. Example: -P {a: 1}, -P '{a: 1, b: duration({seconds: 1})}', or using arrow syntax -P 'a ⇒ 1'. This argument can be specified multiple times.

[]

--non-interactive

Force non-interactive mode. Only useful when auto-detection fails (like on Windows).

false

--sample-rows SAMPLE-ROWS

Number of rows sampled to compute table widths (only for format=VERBOSE)

1000

--wrap {true,false}

Wrap table column values if the column is too narrow (only for format=VERBOSE).

true

-v, --version

Print Cypher Shell version and exit.

false

--driver-version

Print Neo4j Driver version and exit.

false

-f FILE, --file FILE

Pass a file with Cypher statements to be executed. After executing all statements, Cypher Shell shuts down.

--change-password

Change the neo4j user password and exit.

false

--log [LOG-FILE]

Enable logging to the specified file, or standard error if the file is omitted.

--history [HISTORY-BEHAVIOUR]

File path of query and command history file or in-memory for in-memory history. Defaults to <user home>/.neo4j/.cypher_shell_history. It can also be set using the environmental variable NEO4J_CYPHER_SHELL_HISTORY.

--notifications

Enable query notifications in interactive mode.

false

--idle-timeout IDLE-TIMEOUT

Closes the application after the specified amount of idle time in interactive mode. You can specify the duration using the format <hours>h<minutes>m<seconds>s, for example 1h (1 hour), 1h30m (1 hour 30 minutes), or 30m (30 minutes).

disable

Connection arguments

Option Description Default

-a ADDRESS, --address ADDRESS, --uri ADDRESS

Address and port to connect to. Defaults to neo4j://localhost:7687. Can also be specified using the environment variable NEO4J_ADDRESS or NEO4J_URI.

neo4j://localhost:7687

-u USERNAME, --username USERNAME

Username to connect as. Can also be specified using the environment variable NEO4J_USERNAME.

--impersonate IMPERSONATE

User to impersonate.

-p PASSWORD, --password PASSWORD

Password to connect with. Can also be specified using the environment variable NEO4J_PASSWORD.

--encryption {true,false,default}

Whether the connection to Neo4j should be encrypted. This must be consistent with Neo4j’s configuration. If choosing default, the encryption setting is deduced from the specified address. For example, the neo4j+ssc protocol uses encryption.

default

-d DATABASE --database DATABASE

Database to connect to. Can also be specified using the environment variable NEO4J_DATABASE.

--access-mode {read,write}

Access mode. Defaults to WRITE.

write

Running Cypher Shell within the Neo4j distribution

You can connect to a live Neo4j DBMS by running cypher-shell and passing in a username and a password argument:

bin/cypher-shell -u neo4j -p <password>

The output is the following:

Connected to Neo4j at neo4j://localhost:7687 as user neo4j.
Type :help for a list of available commands or :exit to exit the shell.
Note that Cypher queries must end with a semicolon.

Running Cypher Shell from a different server

You can also install the Cypher Shell tool on a different server (without Neo4j) and connect to a Neo4j DBMS. Cypher Shell requires Java 17.

DEB/RPM distributions both install Java, if it is not already installed, and the Cypher Shell executable. The cypher-shell files are available in the same DEB/RPM Linux repositories as Neo4j.

The TAR distribution contains only the cypher-shell files, so you must install Java manually.

  1. Download Cypher Shell from Neo4j Deployment Center.

  2. Connect to a Neo4j DBMS by running the cypher-shell command providing the Neo4j address, a username, and a password:

    cypher-shell/cypher-shell -a neo4j://IP-address:7687 -u neo4j -p <password>

    The output is the following:

    Connected to Neo4j at neo4j://IP-address:7687 as user neo4j.
Type :help for a list of available commands or :exit to exit the shell.
Note that Cypher queries must end with a semicolon.

Changing the access mode

This feature is available in Neo4j 5.20 and later.

By default, the access mode is set to write. However, you can change the access mode to read or write using the --access-mode argument when connecting to a Neo4j DBMS with the cypher-shell command or by using the :access-mode command in the interactive shell. Keep in mind that access mode can affect which servers in a cluster a query can get routed to. For example, a server with modeConstraint=SECONDARY can only do reads.

The following is an example of how you can connect to a Neo4j DBMS in read mode and then change the access mode to write in the interactive shell.

  1. Connect to a Neo4j DBMS in read mode:

    bin/cypher-shell -u neo4j -p <password> --access-mode read
    Connected to Neo4j using Bolt protocol version 5.4 at neo4j://localhost:7687 as user neo4j.
Type :help for a list of available commands or :exit to exit the shell.
Note that Cypher queries must end with a semicolon.

  2. Try to create a node in read access mode:

    create ();
    Writing in read access mode not allowed. Attempted write to neo4j

  3. Change the access mode to write in the interactive shell:

    :access-mode write

  4. Verify the access mode:

    :access-mode
    Access mode write

  5. Create a node in write access mode:

    create ();
    0 rows
ready to start consuming query after 66 ms, results consumed after another 0 ms
Added 1 nodes

For more information on the :access-mode command, run the following command in the interactive shell:

:help access-mode
usage: :access-mode - Display current access mode
:access-mode read - Reconnect with read access mode
:access-mode write - Reconnect with write access mode

Available commands

Once in the interactive shell, run the following command to display all available commands:

Example 1. Running help
:help

The output is the following:

Available commands:
  :access-mode  View or set access mode  (1)
  :begin        Open a transaction
  :commit       Commit the currently open transaction
  :connect      Connects to a database
  :disconnect   Disconnects from database
  :exit         Exit the logger
  :help         Show this help message
  :history      Statement history
  :impersonate  Impersonate user
  :param        Set the value of a query parameter
  :rollback     Rollback the currently open transaction
  :source       Executes Cypher statements from a file
  :sysinfo      Neo4j system information (2)
  :use          Set the active database


For help on a specific command type:
    :help command

Keyboard shortcuts:
    Up and down arrows to access statement history.
    Tab for autocompletion of commands, hit twice to select suggestion from list using arrow keys.

For help on cypher please visit:
    https://neo4j.com/docs/cypher-manual/current/
1 Introduced in Neo4j 5.20
2 Introduced in Neo4j 5.11

Running Cypher statements

You can run Cypher statements in the following ways:

  • Typing Cypher statements directly into the interactive shell.

  • Running Cypher statements from a file with the interactive shell.

  • Running Cypher statements from a file as a cypher-shell argument.

The examples in this section use the MATCH (n) RETURN n LIMIT 5 Cypher statement and will return 5 nodes from the database.

Example 2. Typing a Cypher statement directly into the interactive shell
MATCH (n) RETURN n LIMIT 5;

The following two examples assume a file exists in the same folder you run the cypher-shell command from called example.cypher with the following contents:

MATCH (n) RETURN n LIMIT 5;
Example 3. Running Cypher statements from a file with the interactive shell

You can use the :source command followed by the file name to run the Cypher statements in that file when in the Cypher interactive shell:

:source /path/to/your/example.cypher
Example 4. Running Cypher statements from a file as a cypher-shell argument.

You can pass a file containing Cypher statements as an argument when running cypher-shell.

The examples here use the --format plain flag for a simple output.

Using cat (UNIX)

cat example.cypher | bin/cypher-shell -u neo4j -p <password> --format plain

Using type (Windows)

type example.cypher | bin/cypher-shell.bat -u neo4j -p <password> --format plain

Query parameters

Cypher Shell supports querying based on parameters. Use :param <Cypher Map> to set parameters or the older arrow syntax :param name ⇒ <Cypher Expression>. List current parameters with :param. Clear parameters with :param clear.

Parameters can be set to any Cypher expression. Some expressions need to be evaluated online and require an open session. The parameter expression is evaluated once. For example, :param {now: datetime()} will set the parameter now to the current date and time at the time of setting the parameter.

Example 5. Use parameters within Cypher Shell

  1. Set the parameter alias to Robin and born to date('1940-03-20') using the :param keyword:

    :param {alias: 'Robin', born: date('1940-03-20')}

  2. Check the current parameters using the :params keyword:

    :param
    {
  alias: 'Robin',
  born: date('1981-08-01')
}

  3. Now use the alias and born parameters in a Cypher query:

    CREATE (:Person {name : 'Dick Grayson', alias : $alias, born: $born });
    Added 1 nodes, Set 3 properties, Added 1 labels

  4. Verify the result:

    MATCH (n) RETURN n;
    +--------------------------------------------------------------------+
| n                                                                  |
+--------------------------------------------------------------------+
| (:Person {name: "Bruce Wayne", alias: "Batman"})                   |
| (:Person {name: "Selina Kyle", alias: ["Catwoman", "The Cat"]})    |
| (:Person {name: "Dick Grayson", alias: "Robin", born: 1940-03-20}) |
+--------------------------------------------------------------------+
3 rows available after 2 ms, consumed after another 2 ms

Transactions

Cypher Shell supports explicit and implicit transactions. Transaction states are controlled using the keywords :begin, :commit, and :rollback.

Both explicit and implicit transactions run from Cypher Shell will have default transaction metadata attached that follows the convention (see Attach metadata to a transaction).

Example 6. Use fine-grained transaction control

The example uses the dataset from the built-in Neo4j Browser guide, called MovieGraph. For more information, see the Neo4j Browser documentation.

  1. Run a query that shows there is only one person in the database, who is born in 1964.

    MATCH (n:Person) WHERE n.born=1964 RETURN n.name AS name;
    +----------------+
| name           |
+----------------+
| "Keanu Reeves" |
+----------------+

1 row
ready to start consuming query after 9 ms, results consumed after another 0 ms

  2. Start a transaction and create another person born in the same year:

    :begin
neo4j# CREATE (:Person {name : 'Edward Mygma', born:1964});
    0 rows
ready to start consuming query after 38 ms, results consumed after another 0 ms
Added 1 nodes, Set 2 properties, Added 1 labels

  3. If you open a second Cypher Shell session and run the query from step 1, you will notice no changes from the latest CREATE statement.

    MATCH (n:Person) WHERE n.born=1964 RETURN n.name AS name;
    +----------------+
| name           |
+----------------+
| "Keanu Reeves" |
+----------------+

1 row
ready to start consuming query after 9 ms, results consumed after another 0 ms

  4. Go back to the first session and commit the transaction.

    neo4j# :commit

  5. Now, if you run the query from step 1, you will see that Edward Mygma has been added to the database.

    MATCH (n:Person) WHERE n.born=1964 RETURN n.name AS name;
    +----------------+
| name           |
+----------------+
| "Keanu Reeves" |
| "Edward Mygma" |
+----------------+

2 rows
ready to start consuming query after 1 ms, results consumed after another 1 ms

Procedures

Cypher Shell supports running any procedures for which the current user is authorized.

Example 7. Call the dbms.showCurrentUser procedure
CALL dbms.showCurrentUser();
+------------------------------+
| username | roles     | flags |
+------------------------------+
| "neo4j"  | ["admin"] | []    |
+------------------------------+

1 row available after 66 ms, consumed after another 2 ms

Supported operating systems

You can use the Cypher Shell CLI via cmd on Windows systems, and bash on Unix systems.

Other shells may work as intended, but there is no test coverage to guarantee compatibility.

Keyboard shortcuts

The following keyboard commands are available in interactive mode.

Key Operation

↑ and ↓ (arrow keys)

Access statement history.

↹ (tab)

Autocompletion of commands and Cypher syntax. Suggestions for Cypher syntax is not complete.

Home (key)

Moves the cursor to the first character in the current line.

End (key)

Moves the cursor to the last character in the current line.