The graph database,
in your terminal.

Three credential types share add / list / use / remove. New installs store secrets in the OS keyring by default (macOS Keychain, Windows Credential Store, Linux Secret Service). Switch storage with neo4j-cli config set credential-storage keyring|insecure --rw; insecure writes plaintext credentials.json under your OS config directory.

aura-client — Aura Console API (client ID + secret). Required for any aura … command.

$ neo4j-cli credential aura-client add --name prod --client-id <id> --client-secret <secret> --rw
$ neo4j-cli credential aura-client use prod

dbms — Neo4j Bolt connection profiles (URI, username, password, database). When a default exists, query connects without flags.

$ neo4j-cli credential dbms add --name prod --uri neo4j+s://… --username neo4j --password <pw> --rw
$ neo4j-cli credential dbms set-embed prod openai-shared   # link an embed credential
$ neo4j-cli credential dbms use prod

embed — Embedding providers (openai / ollama / huggingface / gemini / vertex). Consumed by --param NAME:embed=… and query :embed.

$ neo4j-cli credential embed add --name openai-shared --provider openai --model text-embedding-3-small --api-key <key> --rw
$ neo4j-cli credential embed use openai-shared

neo4j-cli config — persistent global settings stored in the OS config directory.

$ neo4j-cli config list                                    # show all settings and current values
$ neo4j-cli config get telemetry
$ neo4j-cli config set telemetry false --rw               # same effect as DO_NOT_TRACK=1
$ neo4j-cli config set skill-auto-refresh false --rw      # disable post-update skill refresh
$ neo4j-cli config set default-output-format json --rw    # change default --format

Connection env vars — override or supplement stored credentials:

NEO4J_URI=neo4j+s://host:7687
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=secret
NEO4J_DATABASE=neo4j
NEO4J_DEBUG=1          # enable driver diagnostics on stderr (same as --debug)

Embedding env vars:

NEO4J_EMBED_PROVIDER=openai          # openai | ollama | huggingface | gemini | vertex
NEO4J_EMBED_MODEL=text-embedding-3-small
NEO4J_EMBED_API_KEY=sk-…             # also reads OPENAI_API_KEY / HF_TOKEN
NEO4J_EMBED_BASE_URL=https://…       # custom endpoint (Ollama, HF dedicated)

Installer & telemetry env vars:

DO_NOT_TRACK=1                        # disable telemetry for this invocation only
NEO4J_CLI_AUTO_INSTALL_SKILL=1        # installer prefix: runs skill install --rw post-install

All env vars are also read from a .env file, which the CLI locates by walking up from the current directory to the git root.

Run Cypher via the Bolt protocol. With a stored dbms credential, no connection flags are needed.

$ neo4j-cli query 'MATCH (n) RETURN count(n) AS n'
$ echo 'MATCH (n) RETURN count(n)' | neo4j-cli query    # stdin
$ neo4j-cli query 'RETURN $ids' --param 'ids=[1,2,3]'  # JSON-typed param
$ neo4j-cli query … --debug                           # driver diagnostics to stderr (NEO4J_DEBUG=1)

Built-in commands — pass instead of a Cypher string:

$ neo4j-cli query :schema              # labels, rel-types, property keys, indexes, constraints
$ neo4j-cli query :schema --format json # machine-readable schema
$ neo4j-cli query :embed "hello world"  # embed text and print vector (no DB needed)

Connection resolution (highest priority first):

• --uri / --username / --password / --database flags
• Env vars: NEO4J_URI, NEO4J_USERNAME, NEO4J_PASSWORD, NEO4J_DATABASE
• .env file (walks up to git root)
• --credential <name> or default stored dbms credential
• Built-in defaults: neo4j://localhost:7687, user neo4j, db neo4j

http:// and https:// URIs are auto-rewritten to neo4j:// / neo4j+s://. For self-signed certs use neo4j+ssc://.

Bind a vector inline with --param NAME:embed=text — text is sent to the configured provider and the resulting []float32 is bound as $NAME for both EXPLAIN preflight and the real query.

$ neo4j-cli query --param 'q:embed=sci-fi movies' --param k=5 \
  "CALL db.index.vector.queryNodes('idx', \$k, \$q) YIELD node, score RETURN node.title, score"

$ neo4j-cli query :embed "hello world" --format json   # standalone, no DB needed

Providers and defaults: openai (api.openai.com/v1) · ollama (localhost:11434, no key) · huggingface (serverless; set --embed-base-url for dedicated endpoint) · gemini (GEMINI_API_KEY / GOOGLE_API_KEY) · vertex (Application Default Credentials; needs --vertex-project + --vertex-location).

Settings resolution (highest first): flag (--embed-provider, --embed-model, …) → env (NEO4J_EMBED_PROVIDER, NEO4J_EMBED_MODEL, …) → .env → stored embed credential → provider defaults.

API-key priority: OPENAI_API_KEY / HF_TOKEN → NEO4J_EMBED_API_KEY → .env → stored credential. One --credential dbms can drive both connection and embedding when the dbms profile carries an embed link.

Requires an aura-client credential. Get client ID + secret from Aura Account Settings.

Aura resources are organized as organization → project → instance. Instance / snapshot / agent / CMK / graph-analytics commands all need an --organization-id + --project-id pair, or a default workspace pinned via workspace use.

$ neo4j-cli aura organization list
$ neo4j-cli aura project list --organization-id <org-id>
$ neo4j-cli aura workspace use <org-id>/<project-id> --rw   # pin default scope
$ neo4j-cli aura instance list --format table
$ neo4j-cli aura instance get <id>
$ neo4j-cli aura instance create --name my-db --type free-db --rw
$ neo4j-cli aura instance create --name prod --type professional-db \
    --cloud-provider aws --region us-east-1 --memory 4GB \
    --wait --rw
$ neo4j-cli aura instance delete <id> --rw
$ neo4j-cli aura instance deploy --from-docker dev --type free-db --rw   # clone a local DB into a new Aura instance

instance create auto-stores DB credentials as a dbms credential named <instance-id>-default so query connects immediately. Pass --no-credential-storage to skip. --wait polls until the instance status is running; --timeout sets the deadline in seconds (default: 300).

aura snapshot — on-demand backups and restores:

$ neo4j-cli aura snapshot list --instance-id <id>
$ neo4j-cli aura snapshot create --instance-id <id> --rw
$ neo4j-cli aura snapshot restore <snapshot-id> --instance-id <id> --rw
$ neo4j-cli aura snapshot delete <snapshot-id> --instance-id <id> --rw

aura graph-analytics — run GDS algorithm jobs against an instance:

$ neo4j-cli aura graph-analytics list --instance-id <id>
$ neo4j-cli aura graph-analytics create --instance-id <id> --algorithm pageRank --rw
$ neo4j-cli aura graph-analytics get <job-id> --instance-id <id>
$ neo4j-cli aura graph-analytics delete <job-id> --instance-id <id> --rw

aura cmk — customer-managed encryption keys:

$ neo4j-cli aura cmk list
$ neo4j-cli aura cmk get <cmk-id>
$ neo4j-cli aura cmk create --name my-key --provider aws --key-arn arn:… --rw
$ neo4j-cli aura cmk delete <cmk-id> --rw

aura agent — LLM-backed assistants bound to an instance. Leaves: list, get, create, update, replace, delete, invoke. --tools takes a JSON array [{type, name, description, config}] with camelCase types: text2cypher, cypherTemplate, similaritySearch.

Run Neo4j locally by shelling out to the host docker CLI. Requires Docker Desktop (or any Docker-compatible runtime aliased to docker) on PATH. Managed containers carry an org.neo4j.cli.managed=true label — no separate state file.

$ neo4j-cli docker create --name dev --wait --rw          # enterprise eval; stores dbms cred
$ neo4j-cli docker create --name dev --edition community --wait --rw
$ neo4j-cli docker list --format table
$ neo4j-cli docker get dev
$ neo4j-cli docker stop dev --rw
$ neo4j-cli docker start dev --wait --rw
$ neo4j-cli docker delete dev --yes --force --rw    # removes container + stored credential

create auto-stores a dbms credential (named after --name) so neo4j-cli query --credential dev connects immediately. Host ports default to 7474/7687 and auto-increment when taken. Pass --version 5.26.0 to pin a Neo4j version; --accept-license upgrades to the commercial license.

--wait polls the Bolt port every second until the container accepts connections. --timeout <seconds> sets the deadline (default: 60). Without --wait, the command returns immediately after docker run exits — the DB may not be ready yet.

Ephemeral containers (--ephemeral) run with docker run --rm — no credential is persisted. Pass --env-out-file <path> to write an env-file for 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 ok'
$ neo4j-cli docker stop tmp --rw   # container auto-removed by Docker

Mount host directories with --data-dir, --logs-dir, or --import-dir to persist data across deletes. --data-dir is incompatible with --ephemeral.

Manage a local Neo4j Desktop 2 install — install the app, lifecycle local DBMSes, install plugins, and register saved remote connections. All commands except install talk to Desktop's local relate API on http://localhost:<port>/fastify/api, so Desktop must be running. --port pins the API port instead of probing 44222..44232.

$ neo4j-cli desktop install --rw                       # install Desktop 2 (DMG / AppImage / NSIS .exe)
$ neo4j-cli desktop install --dry-run --rw             # resolve manifest + URL only, no download
$ neo4j-cli desktop list --format table                # composed view: DBMSes + saved connections
$ neo4j-cli desktop doctor                              # structured health check

dbms — local DBMS lifecycle. Desktop 2 ships enterprise-only; no --edition flag. Only one DBMS may run at a time on port 7687; pass --force on create/start to stop the conflicting one first. --wait polls the relate API every second until status=started; --timeout <seconds> sets the deadline (default: 30).

$ neo4j-cli desktop dbms list --format table
$ neo4j-cli desktop dbms create --name dev --wait --rw     # latest stable version auto-picked
$ neo4j-cli desktop dbms create --name dev --version 2026.04.0 --wait --rw
$ neo4j-cli desktop dbms start <id> --wait --rw
$ neo4j-cli desktop dbms stop <id> --rw
$ neo4j-cli desktop dbms upgrade <id> --rw          # upgrade to latest stable; --version pins, --backup snapshots first
$ neo4j-cli desktop dbms delete <id> --rw

dbms plugin — manage plugins on a Desktop DBMS.

$ neo4j-cli desktop dbms plugin available <dbms-id>        # catalog of installable plugins
$ neo4j-cli desktop dbms plugin list <dbms-id>             # currently installed
$ neo4j-cli desktop dbms plugin install <dbms-id> apoc --rw
$ neo4j-cli desktop dbms plugin uninstall <dbms-id> apoc --rw

connection — saved remote DB connection profiles (Aura, self-hosted, …). Desktop owns the credential — passwords go to safeStorage, not credentials.json.

$ neo4j-cli desktop connection list
$ neo4j-cli desktop connection create --name aura-prod \
    --uri neo4j+s://abc123.databases.neo4j.io --username neo4j --rw      # prompts for password on TTY
$ neo4j-cli desktop connection update <id> --description "dev tier" --rw
$ neo4j-cli desktop connection delete <id> --yes --force --rw

Query against the currently-running Desktop DBMS or a saved connection without restating credentials:

$ neo4j-cli query --credential desktop 'MATCH (n) RETURN count(n)'
$ neo4j-cli query --credential desktop-connection:<uuid> 'MATCH (n) RETURN count(n)'

A local, best-effort log of the commands you have run, written one redacted JSON line per command to history.jsonl (mode 0600) alongside config.json. On by default.

$ neo4j-cli history list                       # last 20 commands, newest first
$ neo4j-cli history list --limit 5              # show the last 5 (0 = all)
$ neo4j-cli history list --format json         # structured entries
$ neo4j-cli history clear --force --rw          # empty the log (destructive)

Secret flag values (--password, --client-secret, --api-key, --uri userinfo, secret-named --param) are redacted before writing; Cypher query bodies are stored verbatim.

Toggle & cap via config keys:

$ neo4j-cli config set history-enabled false --rw   # stop recording
$ neo4j-cli config set history-limit 500 --rw       # cap retained entries

Load a published example Neo4j dataset into a local container, a Desktop 2 DBMS, or a new Aura instance. A dataset is any GitHub <owner>/<repo> carrying a relate.project-install.json manifest — the CLI resolves it, downloads the matching .dump, and loads it.

dataset list — curated suggestions (any manifest-bearing repo works, not just these):

$ neo4j-cli dataset list                       # curated suggestion set
$ neo4j-cli dataset list --format json         # machine-readable

load — the load verb lives on each target's own tree. Datasets are addressed by <owner>/<repo> (e.g. neo4j-graph-examples/movies); --version accepts 5, 5.26, a calver like 2026.04.0, or latest.

$ neo4j-cli docker load neo4j-graph-examples/movies --name movies --wait --rw        # new local container
$ neo4j-cli desktop dbms load neo4j-graph-examples/movies --name movies --rw          # new Desktop 2 DBMS
$ neo4j-cli aura instance load neo4j-graph-examples/movies --name movies --type free-db --rw   # new Aura instance

Loading into an existing target overwrites the --database (default neo4j), which must already exist — pass --force to confirm. aura instance load always creates a new instance (a local Docker daemon stages the dump); datasets needing the graph-data-science plugin can't be loaded into Aura.

--rw — write gate. Required for all state-mutating operations: Cypher writes, credential mutations, config changes, Aura provisioning, Docker container creation, Desktop DBMS management.

$ neo4j-cli query 'CREATE (:Person {name:"Alice"})' --rw
$ neo4j-cli aura instance delete <id> --rw
$ neo4j-cli config set telemetry false --rw

Without --rw, query runs EXPLAIN first and blocks mutating Cypher before execution. --rw is auto-applied on an interactive TTY; must be explicit for agent harnesses (Claude Code, Cursor, Codex, Gemini CLI, Windsurf, Replit, Goose, Devin, Kiro…) and non-interactive scripts (CI, piped, redirected stdout, nohup).

--force — skip safety checks that would otherwise abort a command due to a conflicting resource. Required alongside --yes for all destructive leaves in non-TTY contexts.

$ neo4j-cli docker delete dev --yes --force --rw      # delete even if running
$ neo4j-cli desktop dbms start <id> --force --rw       # stop conflicting DBMS first

--yes — suppress interactive confirmation prompts in destructive operations. In non-TTY contexts (agents, CI, scripts) destructive leaves (… delete / … remove — Aura instance/agent/CMK/snapshot/graph-analytics, docker delete, desktop dbms/connection delete, credential … remove) require both --yes and --force; missing either exits with code 2.

$ neo4j-cli desktop connection delete <id> --yes --force --rw
$ neo4j-cli aura instance delete <id> --yes --force --rw

Disable telemetry without writing config: DO_NOT_TRACK=1 neo4j-cli …

--format — explicit format override. Accepted values: default, json, table, toon (compact, agent-friendly).

$ neo4j-cli query 'MATCH (n) RETURN n LIMIT 5'             # default: table on TTY, JSON when piped
$ neo4j-cli query … --format json                         # {columns, rows, truncated, arrays_truncated}
$ neo4j-cli query … --format table                        # force table even when piped
$ neo4j-cli aura instance list --format table               # management commands support table too
$ neo4j-cli aura instance list --format json

stdio auto-detection — the CLI detects whether stdout is a TTY and adjusts output automatically without any flag.

• Interactive TTY — coloured table, progress spinners, human-readable sizes.
• Piped / redirected — plain text (one value per line for scalars, TSV-like rows for multi-column), no ANSI codes. Safe to pipe into grep, awk, xargs, jq.
• Agent harnesses — detected automatically; default to toon (compact, agent-friendly). Use --format json for structured consumption.

$ neo4j-cli query 'RETURN 42 AS n' | grep n              # plain: "42"
$ neo4j-cli query … --format json | jq '.rows[].n'         # structured JSON pipeline
$ neo4j-cli aura instance list --format json | jq '.[].id'

--max-rows / --truncate-arrays-over — limit result size to avoid flooding stdout.

$ neo4j-cli query … --max-rows 100
$ neo4j-cli query … --max-rows 500 --truncate-arrays-over 10   # cap arrays at 10 elements
$ neo4j-cli query … --truncate-arrays-over 0                  # suppress all arrays

Diagnostic output always goes to stderr (--debug, warnings, error messages) so it never pollutes pipelines that consume stdout.

Self-skill — installs the embedded CLI skill bundle (SKILL.md + per-subcommand refs) into all detected agents:

$ neo4j-cli skill install --rw                       # all detected agents
$ neo4j-cli skill install --agent claude-code --rw    # scope to one agent

neo4j-skills catalog — curated skills for Cypher, GDS, GraphRAG, modeling, drivers, import and more, sourced from neo4j-contrib/neo4j-skills:

$ neo4j-cli skill install --all --rw                 # self-skill + full catalog
$ neo4j-cli skill install neo4j-cypher-skill --rw     # one catalog skill by name
$ neo4j-cli skill install neo4j-cypher-skill --refresh --rw  # force catalog re-fetch first

Manage:

$ neo4j-cli skill list                                 # skills × agents matrix
$ neo4j-cli skill check                                # version drift vs running binary
$ neo4j-cli skill remove neo4j-cypher-skill --rw      # remove a catalog skill
$ neo4j-cli skill remove self --agent windsurf --rw   # remove self-skill from one agent

Supported agents: Claude Code, Cursor, Windsurf, Copilot, Antigravity, Gemini CLI, Cline, Codex, Pi, OpenCode, Junie. Self-skill bundles refresh automatically on binary version change; opt out with neo4j-cli config set skill-auto-refresh false --rw.