Neo4j CLI Tools skill

When to Use

• Cypher queries, schema inspection, Aura, Docker, credentials, agent skills → neo4j-cli (preferred)
• Admin tasks: backup, restore, import, memory sizing → neo4j-admin
• Ad-hoc queries, scripting, CI/CD (Java required) → cypher-shell
• MCP server install → neo4j-mcp

When NOT to Use

• Writing or optimizing Cypher queries → neo4j-cypher-skill
• Upgrading Neo4j drivers or migrating Cypher syntax → neo4j-migration-skill
• Starting a new Neo4j project from scratch → neo4j-getting-started-skill

Available CLI Tools

1. neo4j-cli

Modern unified CLI. Bolt-native Cypher, schema inspection, Aura management, local Docker, credential storage, agent skill catalog install. Single binary — no Java required.

Install:

curl -sSfL https://neo4j.sh/install.sh | bash   # recommended
brew install neo4j-labs/tap/neo4j-cli            # Homebrew
pip install neo4j-cli / pipx install neo4j-cli   # PyPI
npm i -g @neo4j-labs/cli                         # npm

Self-update: neo4j-cli update (also refreshes installed skills automatically)

Key subcommands:

Key patterns:

# Schema-first workflow: always inspect schema before writing Cypher
neo4j-cli query :schema --format toon

# Run Cypher (bolt URIs auto-rewritten; HTTP URIs rewritten to Bolt)
neo4j-cli query "MATCH (n:Person) RETURN n.name LIMIT 5" \
  --uri neo4j+s://xxx.databases.neo4j.io --username neo4j --password $PASS

# Inline embedding parameter (text → vector; $q bound to []float32)
neo4j-cli query "MATCH (c) SEARCH c IN (VECTOR INDEX chunk_embedding FOR \$q LIMIT 5) SCORE AS score RETURN c.text, score" \
  --param q:embed="graph database performance"

# Store a connection profile, then query without flags
neo4j-cli credential dbms add --name prod \
  --uri neo4j+s://xxx.databases.neo4j.io --username neo4j --password $PASS
neo4j-cli query --credential prod "MATCH (n) RETURN count(n)"

# Local Docker: persistent or ephemeral
neo4j-cli docker create --name dev --wait --rw
neo4j-cli query --credential dev 'RETURN 1 AS n'
neo4j-cli docker create --name tmp --ephemeral --env-out-file /tmp/n.env --wait --rw
neo4j-cli query --env /tmp/n.env 'RETURN 1 AS n'

# Install skills from catalog (neo4j-contrib/neo4j-skills)
neo4j-cli skill install                          # self-skill into all detected agents
neo4j-cli skill install neo4j-cypher-skill       # one catalog skill, all agents
neo4j-cli skill install --all                    # self-skill + every catalog skill
neo4j-cli skill install --agent claude-code      # scope to one agent
neo4j-cli skill check                            # detect drift after upgrades

Agent output: Always use --format toon — ~40% fewer tokens than JSON. Set as default: neo4j-cli config set format toon.

Write gate: Write operations require --rw under agent harnesses. Do NOT add it preemptively — if a command fails with "this command writes; pass --rw to allow it", surface the error and ask the user once.

Async operations: instance create/resize/destroy and docker create accept --wait to block until terminal state.

Credentials precedence: flag > OS env (NEO4JURI, NEO4JUSERNAME, NEO4JPASSWORD, NEO4JDATABASE) > .env walk-up > stored credential.

Supported agents: Claude Code, Cursor, Windsurf, Copilot, Gemini CLI, Cline, Codex, OpenCode, Junie, and more.

Full reference: neo4j-cli skill install keeps an always-in-sync skill in your agent.

2. neo4j-admin

Included with Neo4j. Backup, restore, dump/load, CSV import, memory sizing, password reset. Run as Neo4j system user.

Reference: [neo4j-admin-reference.md](references/neo4j-admin-reference.md)

3. cypher-shell

Interactive Cypher REPL. Requires Java 21. Included with Neo4j. Use for ad-hoc queries, file-based batch scripting, CI/CD pipelines.

Reference: [cypher-shell-reference.md](references/cypher-shell-reference.md)

4. aura-cli

Legacy Aura cloud CLI. Prefer neo4j-cli aura for new work — covers all aura-cli operations plus credential storage, Docker, and agent skills.

Reference: [aura-cli-reference.md](references/aura-cli-reference.md)

5. neo4j-mcp

MCP server for AI agent integration. For full install + editor config → use neo4j-mcp-skill (covers Claude Code, Desktop, Cursor, Windsurf, VS Code, Kiro, stdio vs HTTP transport, troubleshooting).

pip install neo4j-mcp-server && neo4j-mcp --version

Reference: [neo4j-mcp-reference.md](references/neo4j-mcp-reference.md)

Backup and Recovery

Edition gate

Online backup requires Enterprise Edition. Community Edition users must use dump/load only (database must be offline).

Backup (Enterprise — database stays online)

# Full online backup — database stays online during backup
neo4j-admin database backup \
  --to-path=/backups/ \
  --database=neo4j \
  --compress

# Differential backup — only changes since last full backup (faster)
neo4j-admin database backup \
  --to-path=/backups/ \
  --database=neo4j \
  --type=DIFF \
  --compress

# Backup to cloud storage (S3, GCS, or HTTPS)
neo4j-admin database backup \
  --to-path=s3://my-bucket/neo4j-backups/ \
  --database=neo4j

Restore (Enterprise)

AGENT GATE — destructive operation: Before running restore, show the user the exact command and target database name, and wait for explicit confirmation. A restore overwrites the existing database.

# Restore from a full or differential backup
# Requires DB to be stopped, or use --force-offline for a running instance
neo4j-admin database restore \
  --from-path=/backups/neo4j-2026-01-15T10-00-00/ \
  --database=neo4j \
  --overwrite-destination=true

# Restore to a new database name (non-destructive path)
neo4j-admin database restore \
  --from-path=/backups/neo4j-2026-01-15T10-00-00/ \
  --database=neo4j-restored

Dump / Load (all editions — database must be offline)

Use for migrations, dev/test data transfers, and Community Edition backups.

# Dump — stop the database first, or pass --force-offline
neo4j-admin database dump --to-path=/exports/ neo4j

# Load — overwrites if target DB exists
neo4j-admin database load \
  --from-path=/exports/neo4j.dump \
  --database=neo4j \
  --overwrite-destination=true

AGENT GATE — destructive operation: Before running load with --overwrite-destination=true, confirm target database name and path with the user.

Key flags

Point-in-time restore strategy

• Full backup: weekly (e.g. every Sunday)
• Differential backup: daily (captures only changes since last full)
• Naming convention: include timestamp in path — e.g. /backups/neo4j-2026-01-19T02-00-00/
• Restore sequence: apply full backup first, then each differential in chronological order

# Example: restore Sunday full + Monday + Tuesday differentials
neo4j-admin database restore \
  --from-path=/backups/neo4j-2026-01-19T02-00-00/ \
  --database=neo4j --overwrite-destination=true

neo4j-admin database restore \
  --from-path=/backups/neo4j-2026-01-20T02-00-00/ \
  --database=neo4j --overwrite-destination=true

neo4j-admin database restore \
  --from-path=/backups/neo4j-2026-01-21T02-00-00/ \
  --database=neo4j --overwrite-destination=true

Environment Variables (neo4j-admin / cypher-shell)

• NEO4JURI / NEO4JADDRESS — connection URI
• NEO4JUSERNAME / NEO4JPASSWORD / NEO4J_DATABASE
• NEO4J_CONF — path to neo4j.conf directory
• NEO4J_HOME — Neo4j installation directory

Precedence: flags > env vars > config files. neo4j-cli uses its own credential store — see neo4j-cli credential dbms.

Resources

• Neo4j Operations Manual
• Cypher Shell Documentation
• Aura CLI GitHub
• Neo4j MCP Documentation
• Neo4j Developer Portal

Checklist

• Correct tool selected: neo4j-cli (preferred) / neo4j-admin / cypher-shell / neo4j-mcp
• If using neo4j-cli: neo4j-cli skill install run after install or upgrade (keeps skill in sync)
• Credentials via env or credential dbms; not hardcoded
• Using --format toon for agent-facing neo4j-cli output
• Destructive ops confirmed before execution
• Post-op verify: connect + SHOW INDEXES + count
• Backup taken before restore or schema change