neo4j-cli-tools-skill

Neo4j CLI ツールスキル

使用する場合

• Cypher クエリ、スキーマ検査、Aura、Docker、認証情報、エージェントスキル → 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、認証情報の保存、エージェントスキルカタログのインストールに対応しています。単一バイナリで、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 Agents を管理します（一覧表示／取得／作成／呼び出し）
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	インストール済みのエージェントスキルを管理します
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

エージェントの出力： 常に --format toon を使用してください。JSON と比べてトークン数を約 40% 削減できます。デフォルトに設定するには、neo4j-cli config set format toon を実行します。

書き込みゲート： エージェントハーネスでは、書き込み操作に --rw が必要です。あらかじめ追加しないでください。コマンドが「this command writes; pass --rw to allow it」というエラーで失敗した場合は、エラーを提示し、ユーザーに一度確認してください。

非同期操作： instance create/resize/destroy と docker create は、終端状態になるまで待機する --wait を指定できます。

認証情報の優先順位： フラグ > OS 環境変数（NEO4J_URI、NEO4J_USERNAME、NEO4J_PASSWORD、NEO4J_DATABASE） > 上位ディレクトリをたどって検索する .env > 保存済みの認証情報。

対応エージェント： Claude Code、Cursor、Windsurf、Copilot、Gemini CLI、Antigravity CLI、Cline、Codex、OpenCode、Junie など。Antigravity の場合、スキルは ~/.gemini/antigravity/skills に配置されます。

完全なリファレンス：neo4j-cli skill install を実行すると、常に最新のスキルがエージェントにインストールされます。

---

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、エージェントスキルに対応しています。

リファレンス：aura-cli-reference.md

5. neo4j-mcp

AI エージェント連携用の 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 の場合は、ダンプ／ロードのみを使用してください（データベースをオフラインにする必要があります）。

バックアップ（Enterprise — データベースはオンラインのまま）

# 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

リストア（Enterprise）

エージェントによる確認 — 破壊的な操作：リストアを実行する前に、正確なコマンドと対象データベース名をユーザーに提示し、明示的な確認を待ってください。リストアを実行すると、既存のデータベースが上書きされます。

# 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

エージェントによる確認 — 破壊的な操作：--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 で指定し、ハードコードしない
• エージェント向けの neo4j-cli 出力には --format toon を使用
• 破壊的な操作は実行前に確認
• 操作後に検証：接続 + SHOW INDEXES + 件数確認
• リストアまたはスキーマ変更の前にバックアップを取得