v1.18.1

Release notes

Highlights

• Aura now knows who's knocking — Aura API and token requests send a User-Agent of Neo4jCLI/<version> (agent|script|human), so Aura can tell agent-driven, scripted and interactive use apart. Your commands don't change; Aura just gets a slightly better-mannered introduction. Example:

  neo4j-cli aura instance list --format json
  

---

Versions

• neo4j-cli: v1.18.1

Changes

neo4j-cli

Patch

• Aura API requests now identify the caller in the User-Agent header as Neo4jCLI/<version> (agent|script|human), so Aura can tell agent-driven, scripted and interactive use apart.

v1.18.0

Release notes

Highlights

• Aura agent evaluations — aura agent evaluation-dataset and aura agent evaluation-run let you build question sets and score an agent against them on accuracy, tool trajectory, groundedness and relevance, so you can see whether your agent is actually any good. Example:

  neo4j-cli aura agent evaluation-run create --agent-id <agent-id> --dataset-id <dataset-id> --metric accuracy --metric groundedness --wait --rw
  

Other changes

• neo4j-cli update and neo4j-cli update check no longer fail with the GitHub API rate-limit error (HTTP 403, exit code 8): release metadata now comes from a static document on neo4j.sh, so no GH_TOKEN or GITHUB_TOKEN is needed or read. Everything else is unchanged.

---

Versions

• neo4j-cli: v1.18.0

Changes

neo4j-cli

Minor

• Adds aura agent evaluation-dataset and aura agent evaluation-run commands for managing Aura agent evaluation datasets and runs

Patch

• neo4j-cli update and neo4j-cli update check no longer fail with the GitHub API rate-limit error (HTTP 403 advising to set GH_TOKEN or GITHUB_TOKEN, exit code 8): release metadata is now fetched from a static document on neo4j.sh instead of the GitHub API, so no token is needed or read. Commands, flags, output, and exit codes are otherwise unchanged.

v1.17.0

Release notes

Highlights

• Desktop projects and tags — desktop project and desktop tag now cover list/create/update/delete, and the new desktop dbms update (plus --project/--tags on desktop connection update) files things where they belong, so your local DBMSes no longer live in one big drawer. Heads-up: in desktop JSON output, project is now projects and it's an array. Example:

  neo4j-cli desktop dbms update my-dbms-id --project "Customer 360" --tags prod,eu --rw
  

• agent-context goes on a diet — the default output is now a compact command index (about 18 KB instead of about 465 KB), so agents can spend their context on your problem rather than our help text. Ask for one command's details by path, or pass --full for the old tree (schema_version is now 2). Example:

  neo4j-cli agent-context aura instance list --format json
  

Other changes

• Unknown flags and commands now print the error, a one-line usage and a Run '<command> --help' hint instead of the entire help text.
• desktop list and desktop connection list work again against Neo4j Desktop 2.3, which reports createdAt as a number.
• On Windows, the skill commands find installed agents when HOME is unset (via %USERPROFILE%), so skill install --all picks up Codex.

---

Versions

• neo4j-cli: v1.17.0

Changes

neo4j-cli

Minor

• New commands for managing projects and tags in a local Neo4j Desktop 2 install: desktop project list/create/update/delete and desktop tag list/create/update/delete manage the Desktop project and tag catalogs. Create and update print the changed entry, failing with an error if Desktop's returned catalog state lacks it; delete prints a minimal confirmation envelope (id and deleted: true). The new desktop dbms update command renames a DBMS, edits its description, or replaces its project/tag assignments. desktop connection update gains matching --project/--tags flags; both take project/tag names or UUIDs (repeatable/comma-separated) with replace semantics, and an empty value clears the assignments. In desktop JSON output, the project field on DBMS and connection objects is renamed to projects and is now an array instead of a single string. On Desktop versions too old to have the projects/tags endpoints, these commands fail with a clear message telling the user to upgrade Neo4j Desktop 2.
• agent-context now prints a compact command index (about 18 KB instead of about 465 KB) by default; pass a command path (e.g. agent-context aura instance list) for that command's details, or --full for the previous complete tree. schema_version is now 2 and commands is a flat list of path/short entries by default.

Patch

• Unknown flags and unknown commands now print the error, a one-line usage and a Run '<command> --help' hint instead of the full help text with all examples.
• Fixed desktop list and desktop connection list failing against Neo4j Desktop 2.3, which reports a connection's createdAt as a numeric timestamp instead of a string.
• On Windows, skill install, skill list, skill remove and skill check now detect installed agents when the HOME environment variable is unset (home is resolved from %USERPROFILE%), so skill install --all works for Codex users (bundled with ChatGPT Desktop on Windows).

v1.16.0

Release notes

Highlights

• aura instance create and aura instance deploy drop --version — Aura's create endpoint now picks the Neo4j version itself and rejects requests that try to set one, so the flag has gone. If a script still passes --version, delete it and the script works again. Example:

  neo4j-cli aura instance create --name my-free-db --type free --rw --format json
  

Other changes

• Usage analytics events now include the parent process binary name (pprocess_binary) when it can be found. It's the file name only, with no directory, so your home path stays out of it.

---

Versions

• neo4j-cli: v1.16.0

Changes

neo4j-cli

Minor

• aura instance create and aura instance deploy no longer accept the --version flag
• Usage analytics events now include the name of the parent process binary that launched the CLI (pprocess_binary, file name only, no directory), when it can be determined

v1.15.0

Release notes

Highlights

• docker create --plugin — Spin up a local container with APOC or Graph Data Science already installed, instead of installing them by hand afterwards. Repeat the flag or pass a comma-separated list. A misspelt name surfaces in docker logs <name>, since the image is the one that installs plugins. Example:

  neo4j-cli docker create --name gds --plugin apoc --plugin graph-data-science --rw
  

• Ctrl-C now stops things — In-flight Aura requests and --wait polling are cancelled when you press Ctrl-C, so the command exits with 130 (143 for SIGTERM) and doesn't keep going. Press Ctrl-C a second time to force-quit. Example:

  neo4j-cli aura instance create --type free --wait --rw
  

• docker delete --remove-volume — Containers made by docker load leave their loaded database in a neo4j-cli-<name>-data volume, and you can now remove it in the same step. On a terminal you're asked (default no). With --yes --force the volume is kept and the cleanup command is printed. The CLI only ever removes the volume it created itself. Example:

  neo4j-cli docker delete movies --remove-volume --yes --force --rw
  

Other changes

• If the Aura API or its auth endpoint can't be reached, times out or sends an unreadable response, Aura commands now exit 8 (retryable) with an error. They used to crash and exit 0.
• An unexpected internal crash now exits 1 and writes to stderr. It used to exit 0 on stdout, which made failures look like successes.
• A corrupt or unreadable config.json now gives a clear error that names the file (exit 1) instead of crashing.
• docker create no longer leaves a running container with a lost password. Credential-store problems now fail before the container starts. docker load and aura instance load run the same checks.
• aura agent commands now report a missing organization or project with the standard default-workspace usage error (exit 2). --organization-id / --project-id are now documented once, on the agent group.
• Aura commands now reject resource IDs containing path or query characters (/, .., ?, #) before sending a request.
• neo4j-cli docker now works when docker is aliased to podman. Listing containers used to fail on podman's JSON format.
• aura graph-analytics session list now fetches every page of sessions, not just the first.

---

Versions

• neo4j-cli: v1.15.0

Changes

neo4j-cli

Minor

• docker create gains --plugin (repeatable, or comma-separated) to install Neo4j plugins such as apoc or graph-data-science in the new container via NEO4J_PLUGINS; the command's result lists them. Plugin names are lower-case letters, digits and hyphens, and a name the image does not know shows up in docker logs <name> when the container starts.
• Pressing Ctrl-C (SIGINT) or sending SIGTERM now stops a running command promptly: in-flight Aura requests and --wait polling are cancelled instead of running to completion, and the command exits with status 130 (143 for SIGTERM). A second Ctrl-C force-quits.
• docker delete can now remove the data volume that a docker load container leaves behind (neo4j-cli-<name>-data, which holds the loaded database): pass --remove-volume, or answer the new prompt on a terminal (default no). With --yes --force and no --remove-volume the volume is kept and the command to remove it later is printed. Only the volume the CLI created for that container is ever removed.

Patch

• Aura commands no longer crash and exit 0 when the Aura API or its authentication endpoint cannot be reached, times out, or sends an unreadable response. They now report an error and exit 8 (upstream, retryable), and Aura commands reject a malformed API response with an error instead of crashing.
• An unexpected internal crash now exits with status 1 (it previously exited 0, so a failed command could look successful) and prints its diagnostic to stderr instead of stdout.
• A corrupt or unreadable config.json now produces a clear error naming the file (exit 1) instead of a crash.
• docker create no longer leaves a running container whose password is lost. A missing credential store, or a reserved or already-stored credential name (for example desktop), now fails before the container is created. If storing the credential fails after the container starts, the password is still shown with a warning; with --no-print-password and a generated password the container is removed and the command fails. docker load and aura instance load apply the same checks.
• aura agent commands now report a missing organization or project with the standard no organization specified; set a default workspace ... usage error (exit 2) instead of required flag(s) ... not set, and the --organization-id and --project-id flags are documented once on the agent group instead of on every subcommand.
• Aura commands now reject organization, project, agent, instance, GraphQL Data API, authentication-provider, virtual-graph, session, snapshot and customer-managed-key IDs that contain path or query characters (such as /, .., ? or #), with a validation error, before sending any request.
• The docker commands now work when docker is aliased to podman. Listing containers (used by docker create, list, get and load) failed with a JSON parse error because podman reports container names and labels in a different shape.
• aura graph-analytics session list now returns all pages of sessions instead of only the first server-defaulted page, so sessions beyond that first page are no longer missing from the output.

v1.14.0

Release notes

Highlights

• EXPLAIN and PROFILE finally show you the plan — the query planner's output is no longer swallowed: --format json and --format toon carry it as a structured plan/profile object, and --format table prints it as an indented operator tree, with PROFILE also reporting per-operator rows, dbHits and time. Example:

  neo4j-cli query "PROFILE MATCH (p:Person) RETURN count(p)" --format table
  

• EXPLAIN of a write no longer needs --rw — EXPLAIN never executes the statement, so making you opt in to writes just to look at a plan was a false alarm. PROFILE does execute, so a PROFILE of a write is still refused without --rw. Example:

  neo4j-cli query "EXPLAIN CREATE (:Person {name: 'Alice'})" --format json
  

---

Versions

• neo4j-cli: v1.14.0

Changes

neo4j-cli

Minor

• query now shows the execution plan for EXPLAIN and PROFILE statements: --format json/toon carry it as a plan or profile object, and --format table prints it as an indented operator tree (PROFILE also reporting per-operator rows, dbHits and time). EXPLAIN of a statement that writes no longer requires --rw (EXPLAIN never executes); PROFILE of a statement that writes is still refused without --rw.

v1.13.0

Release notes

Highlights

• update now tells you what you just installed — self-updating no longer leaves you guessing: after a successful swap the CLI prints the release notes for every version you jumped over, newest first, capped at the three most recent (with a link to the full changelog when older releases are trimmed). --no-changelog if you prefer the strong, silent type, and --format json / --format toon gain a release_notes field plus changelog_url. Example:

  neo4j-cli update
  

• mcp install writes an env block, so capability gates actually work — in config mode the write / Aura / credential gates were previously unreachable without --bundle; now the entry carries the env block that switches them on. A typed --rw enables all three, or scope them individually with the new --allow-writes, --allow-aura, and --allow-credential-write. In bundle mode the flags seed the extension's settings toggles instead of being quietly ignored, and mcp check reports an older entry missing the env block as drift. Example:

  neo4j-cli mcp install --agent claude-desktop --rw --allow-writes
  

Other changes

• graphql cors-policy allowed-origin add / remove return a clear error (exit 8) instead of panicking when the data API answers with an unexpected 2xx status or a malformed CORS policy body, and authorization failures no longer ask you to report an issue that isn't one.
• docker create --no-print-password help text stops pointing at a credential-read command that never existed; it now explains connecting via --credential <name> and resetting the password with admin user set-password plus a credential resync.

---

Versions

• neo4j-cli: v1.13.0

Changes

neo4j-cli

Minor

• neo4j-cli update now prints the release notes for the versions between the old and new version after a successful update, newest first and capped at the 3 most recent (with a link to the full changelog when older releases are omitted). Pass --no-changelog to suppress it. --format json and --format toon gain a release_notes field, plus changelog_url when releases were omitted; --format table is unchanged.

Patch

• Updated docker create --no-print-password help text to no longer reference a credential-read command that does not exist. Now explains how to use the stored credential via --credential <name> and how to reset the password with admin user set-password plus a credential resync.
• mcp install now writes an env block, so write / Aura / credential access actually works with Claude Desktop in config mode (previously unreachable without --bundle). A typed --rw enables all three gates; the new --allow-writes, --allow-aura, and --allow-credential-write flags scope them individually. In bundle mode the flags seed the extension settings toggles instead of being ignored. mcp check reports a pre-existing entry without the env block as drift.
• graphql cors-policy allowed-origin add/remove now return a clear error (exit 8) instead of panicking when the data API responds with an unexpected 2xx status or a malformed CORS policy body, and authorization failure messages no longer say 'please report an issue'.

v1.12.0

Release notes

Highlights

• aura api reaches any Aura endpoint the CLI has no command for — the endpoint carries its own version segment, {org_id}/{project_id} are filled in from your flags or default workspace, and --format json writes the body byte-for-byte so jq can have it. Example:

  neo4j-cli aura api 'v2beta1/organizations/{org_id}/projects' --format json
  

  Non-GET/HEAD methods need --rw, and DELETE also wants confirmation — the escape hatch is not a trapdoor.

• New mcp command group for agents that can't run commands themselves — exposes five tools (target discovery, command listing, docs, read-only run, write run) to MCP clients like Claude Desktop; write, Aura and credential access are each off by default. Example:

  neo4j-cli config set flag.mcp-server true --rw
  neo4j-cli mcp install --agent claude-desktop --bundle --rw
  

  If your agent can already shell out, neo4j-cli skill install remains the better fit.

• Instance creation accepts tier names again — create, deploy and load now take free, professional, business-critical and virtual-dedicated-cloud, the names the API actually asks for. Previously no value worked at all: the old *-db names passed the CLI and were rejected by the API, and the API's names were rejected by the CLI. Example:

  neo4j-cli aura instance create --rw --name my-instance --type professional --cloud-provider aws --region us-east-1 --memory 1GB
  

  The former names still work and are mapped across; professional-ds and enterprise-ds are gone and now say so by name.

Other changes

• --graph-analytics-plugin on a professional instance now actually enables GDS, instead of being silently ignored while every instance defaulted to serverless.
• Aura commands report the API's own message and a non-zero exit code for HTTP 413, 415, 422 and friends, rather than a "please report an issue" note with a success exit code; empty or non-JSON 4xx/5xx bodies keep their status-class exit code too.
• aura instance list now includes organization_id alongside project_id, so the owning organization no longer needs a second lookup.

---

Versions

• neo4j-cli: v1.12.0

Changes

neo4j-cli

Minor

• New neo4j-cli aura api <endpoint> command makes an authenticated request to any Aura API endpoint and prints the response. The endpoint carries its own API version segment (v1/instances, v2beta1/organizations/{org_id}/projects), and {org_id}/{project_id} are substituted from --organization-id/--project-id or the default workspace. Supports --method/-X, repeatable --field/-F and --raw-field/-f (query parameters on GET/HEAD/DELETE, a JSON body otherwise), --input for a verbatim body from a file or stdin, repeatable --header/-H, plus --include/-i and --silent. Non-GET/HEAD methods require --rw and DELETE also requires confirmation (--yes --force when non-interactive). With --format json the response body is written byte-for-byte so it can be piped into jq; a failing status yields the usual error envelope and exit code.
• New neo4j-cli mcp command group (serve, tool, install, remove, list, check, bundle) behind the flag.mcp-server feature flag (NEO4J_CLI_FLAG_MCP_SERVER=1 or neo4j-cli config set flag.mcp-server true). This targets agents and chat surfaces with no filesystem or shell access, which therefore cannot invoke neo4j-cli themselves — Claude Desktop being the reference client. Agents that can already run commands are better served by neo4j-cli skill install. Exposes the CLI through five tools: neo4j_cli_list_targets (discovers reachable Neo4j databases), neo4j_cli_list_commands (lists CLI command trees), neo4j_cli_read_docs (returns documentation from the generated skill bundle), neo4j_cli_run (executes read-only CLI commands), and neo4j_cli_run_write (executes destructive CLI commands, requires --rw). To install into Claude Desktop, run neo4j-cli config set flag.mcp-server true then neo4j-cli mcp install --agent claude-desktop --bundle --rw, which generates a .mcpb bundle and opens the Desktop install UI; omit --bundle to write mcpServers."neo4j-cli" directly into claude_desktop_config.json. Write, Aura and credential access are each off by default and are enabled per-connector in the Desktop settings UI.
• The aura instance list output now includes an organization_id field alongside project_id, so the owning organization of each instance is visible without a separate lookup.

Patch

• Aura commands now report the API's own error message and a non-zero exit code for HTTP 413, 415, 422 and other previously unhandled statuses, instead of a "please report an issue" message with a success exit code. A 4xx or 5xx whose body is empty or not JSON now also keeps its status-class exit code rather than reporting a generic internal failure.
• aura instance create, deploy and load now accept the Aura tier names the API expects: --type free, professional, business-critical and virtual-dedicated-cloud. Previously no value worked — free-db/professional-db/enterprise-db passed the CLI's own check but were rejected by the API with a validation_error, while the names the API asked for were rejected by the CLI as invalid arguments. The former names are still accepted and mapped to their current equivalents; professional-ds and enterprise-ds no longer exist and are now rejected with a message naming the replacement. customer-managed-key create --type is unchanged and still takes the former names.
• instance create/deploy/load: --graph-analytics-plugin on a professional instance now actually enables the GDS plugin (graph_analytics: plugin). Previously the flag was silently ignored by the v2beta1 API and every professional instance defaulted to graph_analytics: serverless regardless of the flag.

v1.11.0

Release notes

Highlights

• neo4j-cli admin — the whole administration tree lands at once — four new subtrees for managing a Neo4j DBMS over Bolt via the system database, with full connection-flag parity with query (--uri, --username, --password, --credential, --env, --debug):

  • admin database — list, get, create, drop, start, stop, with --wait polling on the lifecycle commands.
  • admin user — list, get, create, drop, rename, set-password, suspend, activate.
  • admin role — list, get, create, drop, grant, revoke.
  • admin privilege — grant/deny/revoke each with a per-category subcommand (property, entity, graph, label, load, database, dbms) taking the action as a positional argument, plus admin privilege list. For example: neo4j-cli admin privilege grant property read --on-graph '*' --role analyst.

• Credential env vars now require opt-in via accept-env-vars — the CLI no longer reads credentials out of the environment behind your back; when you do enable it, precedence is uniformly flag > env var > stored, across Aura, DBMS and embed credentials. Partial sets are rejected with a missing-variable error instead of quietly falling back. Breaking: DBMS and embed env vars (covering query and the entire admin tree), plus the NEO4J_DATABASE override alongside --credential, are ignored until this is on. The explicit --database flag is unaffected, and stored credentials are never modified. Set NEO4J_CLI_ACCEPT_ENV_VARS=1 for zero-setup CI with no config file at all. Example:

  neo4j-cli config set accept-env-vars true --rw
  

• aura virtual-graph for Aura Virtual Graphs — create, get, list, update, delete and allowed-configs for virtual graphs in a project. create prints the initial password exactly once as plain_password, so do read the output. list follows the API's pagination on your behalf and mentions on stderr when --limit hid something from you. Example:

  neo4j-cli aura virtual-graph create --rw --name sales-analytics --data-source-id ds-abc123 --import-model-id im-xyz789 --cloud-provider gcp --region europe-west1
  

Other changes

• aura instance list output now includes the instance status.

---

Versions

• neo4j-cli: v1.11.0

Changes

neo4j-cli

Minor

• Add neo4j-cli admin database commands for database lifecycle management (list, get, create, drop, start, stop) with full connection flag parity with query
• add admin user management commands (list, get, create, drop, rename, set-password, suspend, activate)
• Add admin role commands: list, get, create, drop, grant, revoke
• Add admin privilege commands for managing Neo4j Enterprise privileges via the system database. grant/deny/revoke each expose a per-category subcommand (property, entity, graph, label, load, database, dbms) taking the action as a positional argument (e.g. admin privilege grant property read --on-graph * --role analyst), plus admin privilege list
• Add a global accept-env-vars config key (default false) that gates whether the CLI reads credentials from environment variables. Set it with neo4j-cli config set accept-env-vars true --rw, or set NEO4J_CLI_ACCEPT_ENV_VARS=1 for zero-setup CI usage with no config file. When enabled, env vars override stored credentials at the precedence flag > env var > stored, uniformly across Aura (NEO4J_AURA_CLIENT_ID/NEO4J_AURA_CLIENT_SECRET, now synthesized into an ephemeral in-memory credential), DBMS (NEO4J_URI/NEO4J_USERNAME/NEO4J_PASSWORD/NEO4J_DATABASE), and embed (NEO4J_EMBED_*, OPENAI_API_KEY, HF_TOKEN, GEMINI_API_KEY, GOOGLE_API_KEY) credentials; partial sets are rejected with a missing-variable error. BREAKING: DBMS and embed credential env vars are no longer read unless accept-env-vars is enabled — this covers query and the whole admin command tree. BREAKING: the CLI-212 NEO4J_DATABASE override applied alongside --credential now also requires accept-env-vars (the explicit --database flag is unaffected). Stored credentials are never modified.
• aura instance list output now includes the instance status.
• Add aura virtual-graph commands for managing Aura Virtual Graphs in a project: create, get, list, update, delete and allowed-configs. create takes --name, --data-source-id, --import-model-id, --cloud-provider and --region, plus optional --memory, --maximum-bytes-billed and --wait, and prints the initial password once as plain_password. list returns every virtual graph in the project, following the API's pagination on your behalf; --limit caps how many are returned and notes on stderr when more exist

v1.10.0

Release notes

Highlights

• aura graphql commands are out of beta — manage GraphQL Data APIs without flipping a hidden flag, with the full lifecycle plus auth providers and CORS allowed origins. Example:

  neo4j-cli aura graphql create --instance-id 00000000 --name my-api --memory 256MB --type-definitions-file ./typeDefs.graphql --rw
  

• --debug everywhere it was missing — route the underlying API/CLI activity to stderr (stdout stays clean) with secrets redacted, also togglable via NEO4J_DEBUG=1:

  • Aura commands echo HTTP request/response, token acquisition, and polling
  • docker commands echo the docker invocations they shell out to
  • desktop commands echo discovery probes and relate API traffic

• query --database plays nicely with --credential — point a saved or desktop credential at a specific database instead of whatever it shipped with. Example:

  neo4j-cli query "MATCH (n) RETURN count(n)" --credential desktop --database movies --format json
  

Other changes

• query: --database now defaults to the connecting user's home database when unset rather than the literal "neo4j", fixing DatabaseNotFound errors on instances like AuraDB Free where home isn't named "neo4j".

---

Versions

• neo4j-cli: v1.10.0

Changes

neo4j-cli

Minor

• Introduced aura graphql commands for managing GraphQL Data APIs: create, get, list, update, delete, pause, resume, auth-provider, and cors-policy allowed-origin.
• Aura commands now accept a --debug flag (also via NEO4J_DEBUG=1) that routes Aura API request/response activity to stderr with secrets redacted.
• Add --debug to docker commands to echo underlying docker invocations (secrets redacted) to stderr
• Add --debug to desktop commands (also via NEO4J_DEBUG=1) that routes Neo4j Desktop discovery and relate API request/response activity to stderr with secrets redacted
• query: --database flag and NEO4J_DATABASE env var can now be combined with --credential to target a specific database

Patch

• query: --database now defaults to the connecting user's home database when unset instead of the literal "neo4j", fixing DatabaseNotFound errors against instances whose home database is not named "neo4j" (e.g. AuraDB Free, where it is the instance DBID).