Cypher Shell

About Cypher Shell CLI

Cypher Shell is a command-line tool used to run queries and perform administrative tasks against a Neo4j database. 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.

Example of piping a file: cat some-cypher.txt | cypher-shell.

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}]
                    [--enable-autocompletions] [--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] [--idle-timeout IDLE-TIMEOUT]
                    [--error-format {gql,legacy,stacktrace}]
                    [--transaction-timeout TRANSACTION-TIMEOUT] [--fail-fast | --fail-at-end]
                    [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. Completions can only be enabled for neo4j 5 and later.

false

--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 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}' or -P '{a: 1, b: duration({seconds: 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 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], --debug [LOG-FILE]

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

--history HISTORY-BEHAVIOUR

Changed in 2025.08 File path of a query and a command history file, in-memory for in-memory history or disable to disable history. If the option is omitted, history is saved to <user home>/.neo4j/.cypher_shell_history. Can also be set using the environment variable NEO4J_CYPHER_SHELL_HISTORY.

--notifications

Enable 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

--error-format {gql,legacy,stacktrace}

Controls how errors are displayed.

gql Changed in 2025.06

--transaction-timeout TRANSACTION-TIMEOUT

Introduced in 2025.12 Transaction timeout. 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 the 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

Available commands

To see all available commands, run the following command in the interactive shell:

:help;

The output is the following:

Available commands:
  :access-mode  View or set access mode
  :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
  :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/

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.

Examples

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.

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

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:

    bin/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 database access mode

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

Running Cypher statements

You can run Cypher statements by:

  • Typing them directly into the interactive shell.

  • Passing a file with Cypher statements using the :source command.

  • Piping a file with Cypher statements when running cypher-shell from the command line.

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

Typing a Cypher statement directly into the interactive shell

You can type a Cypher statement directly into the interactive shell and run it by ending the statement with a semicolon:

MATCH (n) RETURN n LIMIT 5;

Running Cypher statements from a file in the interactive shell

You can add Cypher statements to a file, for example, example.cypher, and then use the :source command followed by the file name to run the Cypher statements in that file when in the Cypher interactive shell. The file must be in the same folder you run the cypher-shell command from.

example.cypher script
MATCH (n) RETURN n LIMIT 5;
Run Cypher statements from a file in the interactive shell
:source /path/to/your/example.cypher

Piping a file with Cypher statements when running cypher-shell

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

The examples here use the same example.cypher file as in Running Cypher statements from a file in the interactive shell and 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

Using parameters

Cypher Shell supports parameter-based querying. You can use either :param <Cypher Map> to set parameters, or the older arrow syntax :param name ⇒ <Cypher Expression>. In the arrow syntax, expressions are restricted to a single line.

:param without any arguments lists all current parameters, and :param clear clears all parameters.

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()} sets the parameter now to the current date and time at the time of setting the parameter.

The following example demonstrates how to use parameters in 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

Using 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 have default transaction metadata attached that follows the convention described in Attach metadata to a transaction.

Use fine-grained transaction control

The example uses a dataset called the Movie Graph.

  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
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 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. Commit the transaction:

    :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

Transaction timeout
Introduced in 2025.12

You can start Cypher Shell with a specific transaction timeout, which will apply to all transactions during the session.

Start with transaction timeout argument
bin/cypher-shell -u neo4j -p <password> --transaction-timeout 10m

Execute a very long running query.

UNWIND range(0, 90_000) AS x
CALL apoc.util.sleep(100)
RETURN sum(x) AS sum;

After ~10 minutes, the transaction times out.

25N14: invalid transaction state - transaction termination client error. The transaction has been terminated. Retry your operation in a new transaction, and you should see a successful result. Reason: The transaction has not completed within the timeout specified at its start by the client. You may want to retry with a longer timeout.

Using procedures

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

For example, call the dbms.showCurrentUser procedure to show the current user:

CALL dbms.showCurrentUser();
+------------------------------+
| username | roles     | flags |
+------------------------------+
| "neo4j"  | ["admin"] | []    |
+------------------------------+

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

Glossary

allocator

A component in the cluster that allocates databases to servers according to the topology constraints specified and an allocation strategy.

asynchronous replication

Asynchronous replication is used by secondary copies to poll for new transactions, which means they cannot be guaranteed to have received the most recent transactions. This enables efficient scale-out of read-performance.

Aura instance

A fully-managed DBMS represented by a single instance ID, that is running in the Neo4j Aura cloud.

auto-commit transaction

An automatically committed transaction that contains a single query.

Bolt protocol

Bolt is a protocol used for interaction between Neo4j instances and drivers.

bookmark

A marker the client can request from the cluster to ensure that it is able to read its own writes so that the application’s state is consistent and only databases that have a copy of the bookmark are permitted to respond.

category (Bloom)

A category is based on a node label and is defined in a Perspective as a way of visually distinguishing nodes with the same label(s).

causal consistency

All servers in a cluster agree on the order in which transactions take place. The position of a server on the causal chain can be guaranteed using a bookmark.

cluster

A Neo4j DBMS that spans multiple servers working together to increase fault tolerance and/or read scalability. Databases on a cluster may be configured to replicate across servers in the cluster thus achieving read scalability or high availability.

client application

Software that interacts with a Neo4j server.

commit

A commit is the successful completion of a transaction, which ensures durability of any changes made. For more details, visit Operations Manual → Transaction management.

composite database

Composite databases are the means to access partitioned graph data with a single Cypher query.

constraint

Constraints are sets of data modeling rules that ensure the data is consistent and reliable.

Cypher®

Neo4j’s graph query language.

data model

A data model defines how information is organized in a database. A good data model will make querying and understanding your data easier. In Neo4j, the data models have a graph structure.

database

A database is a container used by the DBMS to manage and store graph data. The physical structure of data is controlled by the database.

database vs graph

Databases are the physical containers of graph data. Graphs are the logical structure of data in Neo4j.

Database Management System

Database Management System, or DBMS, capable of managing multiple databases. A DBMS may run on a single server, or span several servers configured as a cluster.

database schema

The prescribed property existence and datatypes for nodes and relationships.

deallocate

An act of removing a database from a server or a server from a cluster without loss of data or reduced fault tolerance.

degree (of a node)

The number of relationships of a specific node; loops are counted twice.

disaster recovery

A manual intervention to restore availability of a cluster, or databases within a cluster.

driver

A software library that provides access to Neo4j from a particular programming language.

election

In the event that the Raft leader becomes unresponsive, followers automatically trigger an election and vote for a new leader.

entity

A node or a relationship.

expression (Cypher)

A component of a Cypher query which produces values. It may be used in projections, as a predicate, or when setting properties on graph elements.

fabric

Fabric is the architectural design of a unified system that provides a single access point to local or distributed graph data.

fault tolerance

A guarantee that a cluster can maintain a database’s persistence and availability in the event of one or more servers failing.

follower

A primary copy of a database acting as a follower, receives and acknowledges synchronous writes from the leader.

Generative AI (GenAI)

A type of artificial intelligence (AI) system that generates text, images, or other media in response to prompts.

graph

A logical representation of a set of nodes where some pairs are connected by relationships.

index

Data structure that improves read performance of a database.

knowledge graph

A specific type of graph that has an organizing principle so that a user (or a computer system) can reason about the underlying data. The organizing principle provides an additional layer of structure that adds context to support knowledge discovery.

label

Marks a node as a member of a named and indexed subset. A node may be assigned zero or more labels.

leader

A single primary copy of a database is designated as the leader. It receives all write transactions from clients and replicates writes synchronously to followers and asynchronously to secondary copies of the database.

main database

In terms of Neo4j Enterprise Studio, the database(s) containing the user’s data. Can exist in the same Neo4j deployment as the tool asset database.

motif

A description of a specific pattern within a graph.

node

A node represents an entity or discrete object in your graph data model. Nodes can be connected by relationships, hold data in properties, and are classified by labels.

operator

A symbol representing a mathematical or logical operation.

parameter

Named value provided when running a Cypher statement.

path

A sequence of nodes and the relationships connecting them, that does not contain duplicate relationships. Several paths can match a pattern.

pattern

A specific arrangement of nodes and relationships that can be matched in a graph. A pattern follows a motif.

perspective (Bloom)

A Perspective defines a certain business view or domain that can be found in the target Neo4j graph. A single Neo4j graph can be viewed through different Perspectives, each tailored for a different business purpose.

primary

A copy of the database that is able to process write transactions and is eligible to be elected as a leader. It participates in fault tolerant writes as it is part of the majority required to acknowledge and commit write transactions.

primary vs secondary

In a cluster, databases can operate in either primary or secondary mode. Primary databases are able to process write and read transactions, ensuring fault tolerance. Secondary databases are replicated asynchronously from primaries, and their main purpose is to provide read scaling within the cluster.

project (Aura)

An isolated environment in the unified Aura console that contains its own database instances, configurations, and resources. Preceded by tenant in the classic Aura console.

property

Properties are key-value pairs that are used for storing data on nodes and relationships.

query (Cypher)

A statement that retrieves or writes information to a database.

Raft group

A group of servers that are participating in hosting a particular database in primary mode.

Raft group member

A server that is participating in a Raft group. A server can be a member of one or more groups.

Raft log

A shared log between all Raft group members that is guaranteed to be consistently updated and viewed by those members. The log contains both database data and operational state of the Raft group.

Raft protocol

The networking mechanism that enables a database to replicate its data across multiple servers to give high availability for accessing the data and high durability to the data stored.

read scaling

Distributing query load by creating additional database copies hosted in secondary mode (read-only).

relationship

A relationship represents a connection between nodes in your graph data model. Relationships connect a source node to a target node, hold data in properties, and are classified by type.

secondary

An asynchronously replicated copy of the database that provides read scaling within the cluster.

seed

A seed is a database dump or a full backup used to create a database on a cluster. This is sometimes called seeding.

server

A physical machine, a virtual machine, or a container running an instance of Neo4j. Servers can be standalone or part of a cluster.

session

A causally linked sequence of transactions.

session consistency

An alternative name for Neo4j’s causal consistency.

standalone

A single server running Neo4j and not part of a cluster.

synchronous replication

Synchronous replication requires the leader primary to replicate a transaction and block the commit until a quorum of the follower primaries acknowledges that the transaction is successfully replicated. Once the transaction is replicated, the commit is allowed to proceed. This ensures data durability and consistency within the cluster.

system database

A database used by Neo4j to store system information.

tenant (Aura)

An isolated environment in the classic Aura console that contains its own database instances, configurations, and resources. Replaced by project in the unified Aura console.

tool asset database

In terms of Neo4j Enterprise Studio, the database where tools' assets are stored. This can be in the same Neo4j deployment as the main database(s) or in a separate deployment.

topology

A configuration that describes how the copies of a database should be spread across the servers in a cluster, see primary mode and secondary mode.

transaction

A transaction comprises a unit of work performed against a database. It is treated in a coherent and reliable way, independent of other transactions. Transactions comply with the ACID consistency model (atomic, consistent, isolated, and durable).