neo4j-cli-tools-skill

# 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:**
```bash
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:**

| Subcommand | Purpose |
|---|---|
| `neo4j-cli query [cypher]` | Run Cypher via Bolt — auto-rewrites HTTP URIs |
| `neo4j-cli query :schema` | Inspect labels, rel types, indexes, constraints |
| `neo4j-cli query :embed [text]` | Compute embedding vector standalone |
| `neo4j-cli aura instance ...` | Provision and manage Aura instances |
| `neo4j-cli aura agent ...` | Manage Aura Agents (list/get/create/invoke) |
| `neo4j-cli docker create/start/stop/delete` | Manage local Neo4j Docker containers |
| `neo4j-cli credential aura-client ...` | Store Aura API credentials |
| `neo4j-cli credential dbms ...` | Store Neo4j connection profiles (URI + auth) |
| `neo4j-cli credential embed ...` | Store embedding provider credentials |
| `neo4j-cli skill install [skill-name]` | Install self-skill or any catalog skill |
| `neo4j-cli skill list / check / remove` | Manage installed agent skills |
| `neo4j-cli update` | Self-update binary + refresh installed skills |

**Key patterns:**
```bash
# 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 (`NEO4J_URI`, `NEO4J_USERNAME`, `NEO4J_PASSWORD`, `NEO4J_DATABASE`) > `.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).

```bash
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)

```bash
# 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 ba