neo4j-cli

name	neo4j-cli
description	Neo4j CLI. Runs and pipes Cypher, introspects the schema, generates a data model, and embeds text inline as a query parameter. Discovers and loads example datasets from GitHub repos into local Docker, Neo4j Desktop, or a new Aura instance. Manages local Neo4j Docker containers and Neo4j Desktop DBMSs; Aura instances, projects, and Agents; and Aura, Neo4j connection (dbms), and embedding-provider credentials. Installs, removes, and refreshes agent skills, and self-updates the binary. Skip for Cypher syntax help, Neo4j drivers, Kubernetes, Neo4j Browser, or other databases.
version	{"[object Object]":null}

neo4j-cli

Allows you to manage Neo4j resources

Allows you to manage Neo4j resources. Write operations require --rw.

Global Flags

Flag	Type	Default	Description
--format	string	-	Format to print console output in, from a choice of [default, json, table, toon]. (agents: prefer toon)
--rw	bool	false	Allow write operations. Auto-applied in interactive terminals; required when running under an agent harness or non-interactive script.

Subcommands

Command	Description
admin	Manage Neo4j databases, users, roles, and privileges
agent-context	Emit the full CLI shape as JSON for AI-agent discovery
aura	Allows you to programmatically provision and manage your Aura resources
config	Manage and view global configuration values
credential	Manage and view credential values
dataset	Discover example Neo4j datasets
desktop	Manage DBMSes under a local Neo4j Desktop 2 install
docker	Manage local Neo4j containers via Docker
history	View and manage the local command history log
query	Run Cypher, inspect the database schema (:schema), and embed text against a Neo4j database via the Bolt protocol
skill	Install agent skills for this CLI into supported AI agents
update	Self-update the neo4j-cli binary

Tips & Gotchas

• Example datasets: neo4j-cli dataset list surfaces a curated suggestion set, but any GitHub <owner>/<repo> carrying a relate.project-install.json manifest can be loaded — the suggestions are not a constraint. Load with the per-target verbs: docker load <owner/repo> (local container), desktop dbms load <owner/repo> (Neo4j Desktop), aura instance load <owner/repo> (new Aura instance). Loading defaults to the latest Neo4j; --database targets a database (default neo4j). Loads are writes, so pass --rw under an agent.
• Before generating ANY Cypher: run neo4j-cli query :schema --format toon first to discover the real labels, relationship types, and properties. Do not guess the schema. Read query-additions.md for the full schema-first workflow, parameters, embeddings, and Cypher 25 vs 5.
• The aura subcommand under neo4j-cli does NOT carry a nested skill group — install agent skills via neo4j-cli skill install at the top level.
• credential lives at the top level of neo4j-cli (not nested under aura) so credentials apply across every subcommand that talks to Aura.
• All read commands accept --format json|table|toon. Write commands print confirmation text only; pipe-friendly output requires explicit --format json where supported.
• Always pass --format toon on read commands — toon uses ~40% fewer tokens than JSON while encoding the same data, so default to it for every list/get/show command. Only use --format json when piping into a JSON-aware tool that requires it; only use --format table when the user explicitly asks for a human-readable table.
• Async resource operations (instance create/resize/destroy) accept --wait to block until the resource reaches a terminal state.
• The version: line in an installed SKILL.md reflects the binary (self-skill) or the cached catalog plugin.json.version (catalog skills). Run neo4j-cli skill check to detect drift; re-run skill install to refresh.
• neo4j-cli skill installs either the embedded self-skill OR any skill from the curated catalog at (Cypher, modeling, drivers, GraphRAG, GDS, Aura, …). The self-skill is addressable as (canonical) or by the binary name (alias) — both are reserved and shadowed catalog entries are rejected. The five leaves take an optional positional plus (case-insensitive) to scope to a single agent. Hard break: a positional that matches an agent name (e.g. ) errors with — no silent fall-through to the old positional-as-agent shape.

# Persistent flow: create stores a dbms credential, then query --credential connects with no further config
neo4j-cli docker create --name dev --wait --rw
neo4j-cli query --credential dev 'RETURN 1 AS n'
neo4j-cli docker delete dev --force --rw

• The generated password appears in docker create's rendered output; redirects and pipes capture it — pass --password <s> to pick your own, --no-print-password to keep the stored credential but omit the password from stdout (the stored credential still connects via --credential <name> — no plaintext needed; the password is not readable through the CLI), or --no-store-credential to suppress storage and rendering. To set a known password, run admin user set-password neo4j --new-password <s> --credential <name> --rw, then resync the stored credential with credential dbms remove <name> plus credential dbms add.

• Persistent volume mounts: --data-dir <host> bind-mounts at /data (persist DB across docker delete), --logs-dir <host> at /logs, --import-dir <host> at /import (for LOAD CSV). Paths support ~ and $VAR expansion; missing dirs are created at mode 0o755. All three are incompatible with --ephemeral. Neo4j adjusts ownership of the mounted dirs at container startup, so they appear under the container's neo4j UID on the host after first start.

# Persist data on the host so it survives delete + recreate
neo4j-cli docker create --name dev --data-dir ~/neo4j-dev/data --rw
neo4j-cli docker delete dev --force --rw
neo4j-cli docker create --name dev --data-dir ~/neo4j-dev/data --rw  # reuses the same data

• Ephemeral runs: neo4j-cli docker create --ephemeral shells docker run --rm, skips credential persistence, and emits a .env blob (NEO4J_URI / NEO4J_USERNAME / NEO4J_PASSWORD / NEO4J_DATABASE) to stdout. With --env-out-file <path> the blob is written to that path (mode 0600) and stdout stays silent so it can be piped into neo4j-cli query --env <path>. The env-file write goes through a temp file in the same directory + atomic rename; a pre-existing symlink at the target path is replaced by a regular file (the symlink is not followed). Docker auto-removes the container when it stops — nothing to delete.

# Ephemeral flow: throwaway container + env-file consumed by query --env
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'
neo4j-cli docker stop tmp --rw

• Aura Agents: neo4j-cli aura agent (list / get / create / update / replace / delete / invoke) manages Aura Agents — LLM-backed assistants bound to an Aura database. --organization-id / --project-id honour the default workspace, identical to every other aura command. invoke is dual-mode: --format json returns the full server response verbatim (content blocks, usage, end_reason, errors), while the default table output joins the text content blocks and prints a single stats line Status: <S> | End reason: <ER> | Tool calls: <N> | Tokens: <req> req / <res> res / <total> total. HTTP 403 on invoke surfaces as agent invocation forbidden: agent may be disabled or private; an HTTP 200 body with type: "error" surfaces as agent invocation failed: <message>.

# List, create, and invoke an agent (workspace default already set)
neo4j-cli aura agent list --format toon
neo4j-cli aura agent create --name docs-bot --description "Docs assistant" --dbid <dbid> --tools '[{"type":"text2cypher","name":"ask","description":"Answer questions about the graph"}]' --rw
neo4j-cli aura agent invoke <agent-id> --input "hello" --rw

• --tools is a JSON array of tool objects. Every tool shares the envelope {type, name, description, config} (plus optional enabled) — name ≤64 chars, description ≤2000 chars. The type discriminator is camelCase (NOT snake_case): text2cypher, cypherTemplate, similaritySearch. The config object is type-specific; the four canonical shapes are:

[{"type":"text2cypher","name":"ask-graph","description":"Convert natural-language questions into Cypher and run them against the database."}]

[{"type":"cypherTemplate","name":"top-customers","description":"Return the top N customers by total order value.","config":{"template":"MATCH (c:Customer)-[:PLACED]->(o:Order) RETURN c.name AS name, sum(o.total) AS spent ORDER BY spent DESC LIMIT $limit","parameters":[{"name":"limit","data_type":"integer","description":"Maximum number of customers to return."}]}}]

[{"type":"similaritySearch","name":"doc-search","description":"Find docs most similar to the user question.","config":{"provider":"openai","model":"text-embedding-3-small","index":"docs_embedding_index","top_k":5}}]

[{"type":"similaritySearch","name":"doc-search-enriched","description":"Vector-search docs, then enrich each hit with its parent page.","config":{"provider":"openai","model":"text-embedding-3-small","index":"docs_embedding_index","top_k":5,"post_processing_cypher":"MATCH (node)<-[:HAS_CHUNK]-(page:Page) RETURN page.title AS title, page.url AS url, node.text AS chunk, score ORDER BY score DESC"}}]

Tool-config field reference (v2beta1):

• text2cypher — no config fields required.
• cypherTemplate.config — required template (Cypher string); optional parameters[] of {name, data_type, description} with data_type ∈ {string, number, boolean, integer}.
• similaritySearch.config — required provider (openai | vertexai), model (provider-compatible embedding model), index (vector-index name, ≤100 chars), top_k (1–100); optional dimensions (integer, when the provider/index needs an explicit size); optional post_processing_cypher — read-only Cypher appended to the vector search and run as a single query, with node and score exposed to the post-processing block (write queries are rejected server-side).