cypher-shell Connect

Establishes and persists a Neo4j connection to ~/.neo4j-connection.

All cypher-shell plugin skills source this file before every command:

source ~/.neo4j-connection 2>/dev/null

This exports the native cypher-shell env vars — cypher-shell reads them automatically:

Interpret $ARGUMENTS

URI argument (contains ://)

1. Parse the URI
2. Ask user for username (default: neo4j) and password
3. Optionally ask for database name
4. Write config:

cat > ~/.neo4j-connection << 'EOF'
export NEO4J_URI="<uri>"
export NEO4J_USERNAME="<user>"
export NEO4J_PASSWORD="<pass>"
export NEO4J_DATABASE="<db>"
EOF

5. Test:

source ~/.neo4j-connection && cypher-shell "RETURN 'connected' AS status;"

6. On success, fetch server info:

source ~/.neo4j-connection && cypher-shell --format verbose "CALL dbms.components() YIELD name, versions, edition RETURN name, versions[0] AS version, edition;"

source ~/.neo4j-connection && cypher-shell --format verbose "SHOW DATABASES YIELD name, currentStatus, default RETURN name, currentStatus, default ORDER BY name;"

Report: version, edition, databases, connection URI.

test or no argument

1. Check ~/.neo4j-connection exists — if not, tell user to run /cypher-shell:connect <uri>
2. Source and test:

source ~/.neo4j-connection && cypher-shell "RETURN 'ok' AS status;"

3. Show config (mask password): URI, user, database.

install

Detect OS:

• macOS: brew install cypher-shell
• Debian/Ubuntu: curl -fsSL https://debian.neo4j.com/neotechnology.gpg.key | sudo gpg --dearmor -o /usr/share/keyrings/neo4j.gpg && echo 'deb [signed-by=/usr/share/keyrings/neo4j.gpg] https://debian.neo4j.com stable latest' | sudo tee /etc/apt/sources.list.d/neo4j.list && sudo apt-get update && sudo apt-get install -y cypher-shell
• Docker fallback: docker run --rm -it --network host neo4j/neo4j:latest cypher-shell

Verify: cypher-shell --version. Requires Java 21+ (java -version).

Protocol Schemes

Troubleshooting

1. Not found -> install
2. Java <21 -> brew install openjdk@21 / sudo apt install openjdk-21-jre
3. Connection refused -> Neo4j not running. Check: lsof -i :7687 or docker ps | grep neo4j
4. Auth failure -> Reset at http://localhost:7474 or use cypher-shell --change-password
5. TLS error -> Try neo4j+ssc:// (self-signed) or bolt:// (no encryption)
6. Routing error -> Use bolt:// for single-server