Cypher Shell
About Cypher Shell CLI
Cypher Shell is a command-line tool that comes with the Neo4j distribution. 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.
cypher-shell [-h] [-a ADDRESS] [-u USERNAME] [--impersonate IMPERSONATE] [-p PASSWORD] [--encryption {true,false,default}] [-d DATABASE] [--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]] [--fail-fast | --fail-at-end] [cypher]
Options
Option | Description |
---|---|
|
An optional string of Cypher to execute and then exit. |
Option | Description | Default |
---|---|---|
|
Show this help message and exit. |
|
|
Exit and report failure on the first error when reading from a file (this is the default behavior). |
|
|
Exit and report failures at end of input when reading from a file. |
|
|
Desired output format, |
|
|
Add a parameter to this session. Example: |
|
|
Force non-interactive mode, only useful if auto-detection fails (like on Windows). |
|
|
Number of rows sampled to compute table widths (only for format=VERBOSE) |
|
|
Wrap table column values if the column is too narrow (only for format=VERBOSE). |
|
|
Print version of cypher-shell and exit. |
|
|
Print version of the Neo4j Driver used and exit. |
|
|
Pass a file with Cypher statements to be executed. After the statements have been executed, |
|
|
Change the |
|
|
Enable logging to the specified file, or standard error if the file is omitted. |
Option | Description | Default |
---|---|---|
|
Address and port to connect to.
Can also be specified using the environment variable |
|
|
Username to connect as. Can also be specified using the environment variable |
|
|
User to impersonate. |
|
|
Password to connect with. Can also be specified using the environment variable |
|
|
Whether the connection to Neo4j should be encrypted. This must be consistent with Neo4j’s configuration. If choosing |
|
|
Database to connect to. Can also be specified using the environment variable |
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. |
-
Download Cypher Shell from Neo4j Download Center.
-
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.
Available commands
Once in the interactive shell, run the following command to display all available commands:
help
:help
The output is the following:
Available commands: :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, list or clear query parameters :rollback Rollback the currently open transaction :source Executes Cypher statements from a file :sysinfo Show Neo4j system information (1) :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.
1 | 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.
MATCH (n) RETURN n LIMIT 5;
The following two examples assume a file exists in the same folder you run the
|
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
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.
-
Set the parameter
alias
toRobin
andborn
todate('1940-03-20')
using the:param
keyword::param {alias: 'Robin', born: date('1940-03-20')}
-
Check the current parameters using the
:params
keyword::param
{ alias: 'Robin', born: date('1981-08-01') }
-
Now use the
alias
andborn
parameters in a Cypher query:CREATE (:Person {name : 'Dick Grayson', alias : $alias, born: $born });
Added 1 nodes, Set 3 properties, Added 1 labels
-
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).
The example uses the dataset from the built-in Neo4j Browser guide, called MovieGraph. For more information, see the Neo4j Browser documentation.
-
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
-
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
-
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
-
Go back to the first session and commit the transaction.
neo4j# :commit
-
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.
dbms.showCurrentUser
procedureCALL 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. |