cypher-shell

Connect to a local instance on the default port (neo4j://localhost:7687)

$ cypher-shell

$ cypher-shell --address neo4j://[host]:[port]

$ cypher-shell --username [username] --password [password]

$ cypher-shell --database [database_name]

$ cypher-shell --file [path/to/file.cypher]

$ cypher-shell --log [path/to/file.log]

$ cypher-shell --help

cypher-shell [OPTIONS]

-u, --uri
    Specifies the Neo4j connection URI (e.g., bolt://localhost:7687).

-a, --auth
    Provides authentication details in username/password format (e.g., neo4j/secret).

-d, --database
    Connects to a specific database within the Neo4j instance (e.g., neo4j, mydb).

-p, --password
    Directly provides the password. Caution: Not recommended for security reasons as it exposes credentials in history/process list.

-f, --file
    Executes Cypher queries from the specified file.

--non-interactive
    Runs the shell in non-interactive mode, suitable for scripting where no user input is expected.

--format
    Sets the output format (e.g., plain, csv, json).

--encrypted
    Forces an encrypted connection to the database via TLS/SSL.

--no-encryption
    Disables encryption for the connection, establishing a plain text connection.

--trust-strategy
    Defines the trust strategy for encrypted connections (e.g., TRUST_ALL_CERTIFICATES, TRUST_SYSTEM_CA_ROOTS).

--trust-certificate
    Specifies the path to a trusted certificate file when using certificate-based trust strategies.

--verbose
    Enables verbose output for debugging and detailed information about connection and execution.

--version
    Displays the version of cypher-shell being used.

--help
    Displays a help message with available options and usage examples.

The cypher-shell is the official command-line interface (CLI) for interacting with a Neo4j graph database. It provides a robust and efficient way to connect to a running Neo4j instance, execute Cypher queries, and retrieve results directly from your terminal.

It supports both interactive sessions, where you can type queries directly, and non-interactive modes, making it ideal for scripting, automated administration tasks, and integrating Cypher queries into larger workflows.

Developed to leverage Neo4j's high-performance Bolt protocol for secure and efficient communication, cypher-shell offers features like result formatting (e.g., plain, CSV, JSON), transaction management, and robust error handling. It's an essential tool for developers, administrators, and data scientists working with Neo4j, offering a lightweight alternative to graphical user interfaces for database interaction.

Using the --password option directly on the command line is insecure as it can expose credentials in process lists or shell history. It's highly recommended to use the interactive password prompt (if not in non-interactive mode) or environment variables for sensitive authentication.

cypher-shell requires a running Neo4j database server to connect to. It does not provide server management capabilities, only query execution against an existing instance.

cypher-shell is highly suitable for scripting and automated tasks. You can pass a file containing Cypher queries using the -f or --file option, often combined with --non-interactive for headless execution. You can also pipe queries directly to it.

Example of running a script and outputting CSV: cypher-shell -u bolt://localhost:7687 -a neo4j/password -f /path/to/queries.cypher --non-interactive --format csv > results.csv

In interactive mode, each query is typically run in its own implicit transaction. For multi-statement operations that require atomic execution, you can wrap them within explicit BEGIN, COMMIT, and ROLLBACK statements directly in the shell or within a script file.

cypher-shell was introduced as the modern, lightweight command-line client for Neo4j, starting with Neo4j 3.0. It was developed to replace the older, Java-based neo4j-shell and to align with the new, high-performance Bolt protocol for database communication. This transition aimed to provide a more streamlined, standard CLI experience and better integration with modern scripting environments, leveraging native compilation for improved startup times and reduced resource usage.

neo4j(1), psql(1), mysql(1), mongo(1), sqlite3(1)