neo4j-cli-tools-skill

Neo4j CLI 工具技能

适用场景

• Cypher 查询、模式检查、Aura、Docker、凭据、Agent 技能 → neo4j-cli（首选）
• 管理任务：备份、恢复、导入、内存配置 → neo4j-admin
• 临时查询、脚本编写、CI/CD（需要 Java）→ cypher-shell
• 安装 MCP 服务 → neo4j-mcp

不适用场景

• 编写或优化 Cypher 查询 → neo4j-cypher-skill
• 升级 Neo4j 驱动程序或迁移 Cypher 语法 → neo4j-migration-skill
• 从头开始启动 Neo4j 项目 → neo4j-getting-started-skill

可用 CLI 工具

1. neo4j-cli

现代化的统一 CLI。原生支持 Bolt 的 Cypher、模式检查、Aura 管理、本地 Docker、凭据存储和 Agent 技能目录安装。单个二进制文件，无需 Java。

安装：

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

自行更新： neo4j-cli update（也会自动刷新已安装的技能）

主要子命令：

子命令	用途
neo4j-cli query [cypher]	通过 Bolt 运行 Cypher — 自动重写 HTTP URI
neo4j-cli query :schema	检查标签、关系类型、索引和约束
neo4j-cli query :embed [text]	独立计算嵌入向量
neo4j-cli aura instance ...	配置和管理 Aura 实例
neo4j-cli aura agent ...	管理 Aura Agent（列出/获取/创建/调用）
neo4j-cli docker create/start/stop/delete	管理本地 Neo4j Docker 容器
neo4j-cli credential aura-client ...	存储 Aura API 凭据
neo4j-cli credential dbms ...	存储 Neo4j 连接配置文件（URI + 身份验证）
neo4j-cli credential embed ...	存储嵌入服务提供商凭据
neo4j-cli skill install [skill-name]	安装自身技能或目录中的任意技能
neo4j-cli skill list / check / remove	管理已安装的 Agent 技能
neo4j-cli update	更新二进制文件并刷新已安装的技能

主要用法模式：

# 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 输出： 始终使用 --format toon — 比 JSON 少约 40% 的令牌。设为默认格式：neo4j-cli config set format toon。

写入门控： 在 Agent 执行环境下，写入操作需要 --rw。请勿预先添加此参数 — 如果命令因“this command writes; pass --rw to allow it”而失败，请显示错误并向用户询问一次。

异步操作： instance create/resize/destroy 和 docker create 接受 --wait，可阻塞直到进入终止状态。

凭据优先级： 标志 > 操作系统环境变量（NEO4J_URI、NEO4J_USERNAME、NEO4J_PASSWORD、NEO4J_DATABASE）> 向上查找 .env > 已存储的凭据。

支持的 Agent： Claude Code、Cursor、Windsurf、Copilot、Gemini CLI、Antigravity CLI、Cline、Codex、OpenCode、Junie 等。Antigravity：技能会放在 ~/.gemini/antigravity/skills 中。

完整参考：neo4j-cli skill install 会在你的 Agent 中安装一项始终保持同步的技能。

---

2. neo4j-admin

随 Neo4j 一同提供。用于备份、恢复、转储/加载、CSV 导入、内存配置和密码重置。以 Neo4j 系统用户身份运行。

参考：neo4j-admin-reference.md

3. cypher-shell

交互式 Cypher REPL。需要 Java 21。随 Neo4j 一同提供。用于临时查询、基于文件的批处理脚本和 CI/CD 流水线。

参考：cypher-shell-reference.md

4. aura-cli

旧版 Aura 云 CLI。新工作请优先使用 neo4j-cli aura — 除涵盖 aura-cli 的所有操作外，还支持凭据存储、Docker 和 Agent 技能。

参考：aura-cli-reference.md

5. neo4j-mcp

用于集成 AI Agent 的 MCP 服务。完整安装和编辑器配置 → 使用 neo4j-mcp-skill（涵盖 Claude Code、Desktop、Cursor、Windsurf、VS Code、Kiro、stdio 与 HTTP 传输方式以及故障排除）。

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

参考：neo4j-mcp-reference.md

备份与恢复

版本限制

在线备份需要 Enterprise Edition。Community Edition 用户只能使用转储/加载方式（数据库必须处于离线状态）。

备份（企业版 — 数据库保持在线）

# 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

恢复（企业版）

Agent 确认门槛 — 破坏性操作：运行恢复前，向用户展示确切命令和目标数据库名称，并等待明确确认。恢复会覆盖现有数据库。

# 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

转储 / 加载（所有版本 — 数据库必须处于离线状态）

适用于迁移、开发/测试数据传输以及 Community Edition 备份。

# 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 确认门槛 — 破坏性操作：使用 --overwrite-destination=true 运行加载前，请与用户确认目标数据库名称和路径。

关键标志

标志	说明
--compress	对备份归档进行 Zstd 压缩
--type=DIFF	差异备份：仅包含自上次完整备份以来的更改
--to-path	本地路径或 s3://、gs://、https://
--overwrite-destination=true	目标数据库已存在时必需
--force-offline	在某些情况下允许备份/恢复正在运行的数据库

时间点恢复策略

• 完整备份：每周一次（例如每周日）
• 差异备份：每日一次（仅记录自上次完整备份以来的更改）
• 命名约定：在路径中包含时间戳 — 例如 /backups/neo4j-2026-01-19T02-00-00/
• 恢复顺序：先应用完整备份，再按时间顺序应用每个差异备份

# 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

---

环境变量（neo4j-admin / cypher-shell）

• NEO4J_URI / NEO4J_ADDRESS — 连接 URI
• NEO4J_USERNAME / NEO4J_PASSWORD / NEO4J_DATABASE
• NEO4J_CONF — neo4j.conf 目录的路径
• NEO4J_HOME — Neo4j 安装目录

优先级：标志 > 环境变量 > 配置文件。neo4j-cli 使用自己的凭据存储 — 参见 neo4j-cli credential dbms。

资源

• Neo4j 运维手册
• Cypher Shell 文档
• Aura CLI GitHub
• Neo4j MCP 文档
• Neo4j 开发者门户

---

检查清单

• 已选择正确的工具：neo4j-cli（首选）/ neo4j-admin / cypher-shell / neo4j-mcp
• 若使用 neo4j-cli：安装或升级后已运行 neo4j-cli skill install（确保技能保持同步）
• 通过环境变量或 credential dbms 提供凭据；未硬编码
• 面向 Agent 的 neo4j-cli 输出使用 --format toon
• 执行前已确认破坏性操作
• 操作后验证：连接 + SHOW INDEXES + 计数
• 恢复或更改架构前已进行备份