Cypher Shell

Describes Neo4j Cypher Shell command-line interface (CLI) and how to use it.

1. 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.

2. 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.

3. Running Cypher Shell

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

Example 1. Running cypher-shell with username and password
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.

4. Available commands

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

Example 2. Running help
:help

The output is the following:

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

5. 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 3. 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 4. 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 example.cypher
Example 5. 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

6. Query parameters

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

Example 6. Use parameters within Cypher Shell
  1. Set the parameter thisAlias to Robin using the :param keyword:

    :param thisAlias => 'Robin'
  2. Check the parameter using the :params keyword:

    :params
    :param thisAlias => 'Robin'
  3. Now use the parameter thisAlias in a Cypher query:

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

7. Transactions

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

Example 7. 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

8. Procedures

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

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

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

9. 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.