31.1. Starting the shell

When used together with a Neo4j server, simply issue the following at the command line:

./bin/neo4j-shell

Under windows, the command is named Neo4jShell.bat.

For the full list of options, see the reference in the Shell manual page.

To connect to a running Neo4j database, use the section called “Read-only mode” for local databases and see the section called “Enabling the shell server” for remote databases.

You need to make sure that the shell jar file is on the classpath when you start up your Neo4j instance.

Enabling the shell server

Shell is enabled from the main configuration of Neo4j, see Section 24.5, “Configuration Settings”. Here’s the available settings:

Settings for the remote shell extension

NameDescription

remote_shell_enabled

Enable a remote shell server which Neo4j Shell clients can log in to.

remote_shell_host

Remote host for shell.

remote_shell_name

The name of the shell.

remote_shell_port

The port the shell will listen on.

remote_shell_read_only

Read only mode.

remote_shell_enabled

Description

Enable a remote shell server which Neo4j Shell clients can log in to.

Valid values

remote_shell_enabled is a boolean.

Default value

false

remote_shell_host

Description

Remote host for shell. By default, the shell server listens only on the loopback interface, but you can specify the IP address of any network interface or use +<<config_0.0.0.0,0.0.0.0>>+ for all interfaces.

Valid values

remote_shell_host is a string which must be a valid name.

Default value

127.0.0.1

remote_shell_name

Description

The name of the shell.

Valid values

remote_shell_name is a string which must be a valid name.

Default value

shell

remote_shell_port

Description

The port the shell will listen on.

Valid values

remote_shell_port is an integer which must be a valid port number (is in the range 1 to 65535).

Default value

1337

remote_shell_read_only

Description

Read only mode. Will only allow read operations.

Valid values

remote_shell_read_only is a boolean.

Default value

false

There are two ways to start the shell, either by connecting to a remote shell server or by pointing it to a Neo4j store path.

Connecting to a shell server

To start the shell and connect to a running server, run:

neo4j-shell

Alternatively supply -port and -name options depending on how the remote shell server was enabled. Then you’ll get the shell prompt like this:

neo4j-sh (0)$

Pointing the shell to a path

To start the shell by just pointing it to a Neo4j store path you run the shell jar file. Given that the right neo4j-kernel-<version>.jar and jta jar files are in the same path as your neo4j-shell-<version>.jar file you run it with:

$ neo4j-shell -path path/to/neo4j-db

Read-only mode

By issuing the -readonly switch when starting the shell with a store path, changes cannot be made to the database during the session.

$ neo4j-shell -readonly -path path/to/neo4j-db

Run a command and then exit

It is possible to tell the shell to just start, execute a command and then exit. This opens up for uses of background jobs and also handling of huge output of f.ex. an ls command where you then could pipe the output to less or another reader of your choice, or even to a file.

And even to another neo4j-shell, e.g. for importing a dump of another database or cypher result. When used with command mode the shell will not output a welcome message. So some examples of usage:

$ neo4j-shell -c "cd -a 24 && set name Mattias"
$ neo4j-shell -c "trav -r KNOWS" | less

Pass Neo4j configuration options

By setting the -config switch, you can provide a properties file that will be used to configure your Neo4j instance, if started in embedded mode.

$ neo4j-shell -config conf/neo4j.properties -path mydb

Execute a file and then exit

To execute commands from a file and then exit just provide a -file filename. This is faster than piping to the shell which still handles the input as if it was user input.

For example reading a dump file directly from the command line and executing it against the given database. For example:

$ neo4j-shell -file export.cql > result.txt

Supplying - as the filename reads from stdin instead.