Cypher Shell

About Cypher Shell CLI

Cypher Shell is a command-line tool that comes with the Neo4j installation. It can also be downloaded from Neo4j Download Center and installed separately.

Cypher Shell CLI is 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.

Syntax

The Cypher Shell CLI is located in the bin directory if installed as part of the product.

The syntax is:

cypher-shell [-u USERNAME, --username USERNAME]
              [cypher]
              [-h, --help]
              [--fail-fast]
              [--fail-at-end]
              [--format]
              [--debug]
              [--non-interactive]
              [-v, --version]
              [-a ADDRESS, --address ADDRESS]
              [-p PASSWORD, --password PASSWORD]
              [--encryption]
              [-d DATABASE, --database DATABASE]
              [--P PARAM, --param PARAM]
              [--sample-rows SAMPLE-ROWS]
              [--wrap]
              [--driver-version]
              [-f FILE, --file FILE]

Arguments

Argument Type Description Default value

-u USERNAME, --username USERNAME

Connection argument

Username to connect as. It can also be specified by the environment variable NEO4J_USERNAME.

cypher

Positional argument

An optional string of cypher to execute and then exit.

-h, --help

Optional argument

Show help message and exit.

--fail-fast

Optional argument

Exit and report failure on first error when reading from file.

This is the default behavior.

--fail-at-end

Optional argument

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

--format {auto,verbose,plain}

Optional argument

Desired output format.

auto (default) displays results in tabular format if you use the shell interactively and with minimal formatting if you use it for scripting.

verbose displays results in tabular format and prints statistics.

plain displays data with minimal formatting.

--debug

Optional argument

Print additional debug information.

false

--non-interactive

Optional argument

Force non-interactive mode; only useful if auto-detection fails (e.g. Windows).

false

-v, --version

Optional argument

Print version of cypher-shell and exit.

false

-a ADDRESS, --address ADDRESS

Connection argument

Address and port to connect to.

neo4j://localhost:7687

-p PASSWORD, --password PASSWORD

Connection argument

Password to connect with. It can also be specified by the environment variable NEO4J_PASSWORD.

--encryption {true,false,default}

Connection argument

Whether the connection to Neo4j should be encrypted; must be consistent with Neo4j’s configuration.

default - the encryption setting is deduced from the specified address. For example, the neo4j+ssc protocol would use encryption.

-d DATABASE, --database DATABASE

Connection argument

Database to connect to. It can also be specified by the environment variable NEO4J_DATABASE.

--P PARAM, --param PARAM

Optional argument

Add a parameter to this session. For example, -P "number ⇒ 3" or -P "country ⇒ 'Spain'". This argument can be specified multiple times.

--sample-rows SAMPLE-ROWS

Optional argument

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

1000

--wrap {true,false}

Optional argument

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

true

--driver-version

Optional argument

Print version of the Neo4j Driver used and exit.

false

-f FILE, --file FILE

Optional argument

Pass a file with cypher statements to be executed. After the statements have been executed cypher-shell shuts down.
Example 1. Invoke cypher-shell with username and password
$neo4j-home> bin/cypher-shell -u neo4j -p <password>
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.
neo4j>
Example 2. Invoke help
neo4j> :help
Available commands:
  :begin    Open a transaction
  :commit   Commit the currently open transaction
  :exit     Exit the logger
  :help     Show this help message
  :history  Print a list of the last commands executed
  :param    Set the value of a query parameter
  :params   Prints all currently set query parameters and their values
  :rollback Rollback the currently open transaction
  :source   Interactively executes Cypher statements from a file
  :use      Set the active database

For help on a specific command type:
  :help command
Example 3. Execute a query
neo4j> MATCH (n) RETURN n;
+-----------------------------------------------------------------+
| n                                                               |
+-----------------------------------------------------------------+
| (:Person {name: "Bruce Wayne", alias: "Batman"})                |
| (:Person {name: "Selina Kyle", alias: ["Catwoman", "The Cat"]}) |
+-----------------------------------------------------------------+
Example 4. Invoke cypher-shell with a Cypher script

The contents of a file called examples.cypher:

MATCH (n) RETURN n;

MATCH (batman:Person {name: 'Bruce Wayne'}) RETURN batman;

Invoke the examples.cypher script from the command-line. All the examples in the remainder of this section use the --format plain flag for a simple output.

Using cat (UNIX)

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

Using type (Windows)

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

Result

n
(:Person {name: "Bruce Wayne", alias: "Batman"})
(:Person {name: "Selina Kyle", alias: ["Catwoman", "The Cat"]})
batman
(:Person {name: "Bruce Wayne", alias: "Batman"})

Query parameters

Cypher Shell CLI supports querying based on parameters. This is often used while scripting.

Example 5. Use parameters within Cypher Shell

Set the parameter thisAlias to Robin using the :param keyword. Check the parameter using the :params keyword.

neo4j> :param thisAlias => 'Robin'
neo4j> :params
:param thisAlias => 'Robin'

Now use the parameter thisAlias in a Cypher query. Verify the result.

neo4j> CREATE (:Person {name : 'Dick Grayson', alias : $thisAlias });
Added 1 nodes, Set 2 properties, Added 1 labels
neo4j> 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"})                |
+-----------------------------------------------------------------+
3 rows available after 2 ms, consumed after another 2 ms

Transactions

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

Example 6. Use fine-grained transaction control

Start a transaction in your first Cypher Shell session:

neo4j> 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"})                |
+-----------------------------------------------------------------+
3 rows available after 2 ms, consumed after another 2 ms
neo4j> :begin
neo4j# CREATE (:Person {name : 'Edward Mygma', alias : 'The Riddler' });

If you open a second Cypher Shell session, you will notice no changes from the latest CREATE statement.

neo4j> 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"})                |
+-----------------------------------------------------------------+
3 rows available after 2 ms, consumed after another 2 ms

Go back to the first session and commit the transaction.

neo4j# :commit
0 rows available after 1 ms, consumed after another 0 ms
Added 1 nodes, Set 2 properties, Added 1 labels
neo4j> 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"})                |
| (:Person {name: "Edward Mygma", alias: "The Riddler"})          |
+-----------------------------------------------------------------+
4 rows available after 1 ms, consumed after another 1 ms

neo4j>

Procedures

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

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

1 row available after 66 ms, consumed after another 2 ms
neo4j> :exit

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.