CHANGELOG.md

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, adheres to Semantic Versioning, and is generated by Changie.

The historical CHANGELOG-aura.md covers the now-discontinued standalone aura-cli binary.

v1.14.0 - 2026-08-26

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 - 2026-08-17

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 - 2026-08-14

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 - 2026-07-30

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 - 2026-06-10

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).

v1.9.0 - 2026-06-05

Minor

• Add neo4j-cli aura instance deploy to clone a local Neo4j database (from a managed Docker container or a Neo4j Desktop DBMS) into a new Aura instance.
• Failing commands now save their full redacted output to a tee file under the config directory (neo4j/cli/tee) and expose its path as tee_path in the JSON/toon error envelope; controlled by the new tee-enabled and tee-limit config keys.
• Rendered output field names are now snake_case across docker (bolt_port, http_port), credential (database_name, embed_credential, base_url, vertex_project, vertex_location), workspace (organization_id, project_id, project_name), and desktop (connection_uri, pending_restart, file_path) commands. BREAKING: scripts parsing JSON/TOON keys or table headers must update to the snake_case names. CLI flags, config keys, and Docker label identifiers are unchanged.
• Add dataset list and per-target load commands (docker load, desktop dbms load, aura instance load) to load example datasets from neo4j-graph-examples repos.
• Fix default output reverting to JSON instead of table in interactive terminals; default to TOON when run by an AI agent

Patch

• skill check and skill list now report each catalog skill's available version from that skill's own remote SKILL.md version: instead of a single shared plugin.json version.
• neo4j-cli history list and telemetry now report invoker "script" for non-TTY, non-agent invocations (piped, CI, cron); these were previously reported as "agent".

v1.8.0 - 2026-06-02

Minor

• query: accept multiple statements separated by ; at line end; --atomic runs them in a single transaction; --continue-on-error keeps going past failing statements (non-atomic only); write statements now report summary stats (nodes/relationships/properties created, etc.); comment-only statements are skipped instead of erroring
• Clearer feedback signposting: the installer now prints the GitHub issues URL, the bug-report link in error messages is corrected, and Bolt auth/connection and embedding API-key errors now include actionable next-step suggestions.
• Add neo4j-cli history command (list, clear) that records a local log of recently run commands; secret flag values are redacted but query Cypher is stored verbatim. Toggle with config set history-enabled and cap with history-limit.
• desktop: discover the local Neo4j Desktop 2 API via mDNS/DNS-SD (_neo4j-desktop-2._tcp.local), so it's found even on non-standard or ephemeral ports; the 44222..44232 port scan remains a fallback. On macOS a dns-sd tier covers Local Network restrictions — if discovery still fails, pass --port.
• desktop: add neo4j-cli desktop dbms upgrade <id> to upgrade a Desktop-managed DBMS to a newer Neo4j version, with --plugin-upgrade-mode (all|none|upgradable, default upgradable), --version (auto-picks the latest stable enterprise version when omitted), --no-migrate, --backup, and --force.
• aura agent invoke now prints the agent invocation id on success and failure for support/tracing

v1.7.0 - 2026-05-28

Minor

• Credentials are now stored securely in the OS keyring by default (macOS Keychain, Windows Credential Store, Linux Secret Service). Existing credentials remain in plaintext until you run neo4j-cli config set credential-storage keyring. To keep plaintext storage, no action is required.
• 'neo4j-cli skill install ' no longer accepts a positional agent name — use --agent instead. New: install any skill from the curated neo4j-contrib/neo4j-skills catalog, plus --all, --refresh, and a new 'skill refresh' leaf.
• Removed deprecated --await alias; --wait is now the only spelling (CLI-111).
• Remove deprecated 'aura tenant list/get' commands and '--tenant-id' flag (deprecated in v1.4.0). Use 'aura project list', 'aura project get' (configuration details) or 'aura organization get' (org metadata), and '--project-id' instead.
• Added Gemini and Vertex AI embedding providers.

Patch

• Credentials stored in plaintext JSON are silently used and automatically migrated to the OS keyring when credential-storage is set to keyring, preventing hard errors from out-of-sync state.
• Add OPTIONAL MATCH, vector and full-text search to the query skill's Virtual Graph forbidden-construct list

v1.6.0 - 2026-05-25

Minor

• Add 'neo4j-cli desktop' subtree for local Neo4j Desktop 2: 'desktop install' installs the app; 'desktop dbms' lifecycles local DBMSes (--wait on async leaves); 'desktop dbms plugin' manages plugins; 'desktop connection' manages saved remote connections; 'desktop list' shows both; 'desktop doctor' runs a structured health check. 'query --credential desktop' or 'desktop-connection:' reads Desktop credentials on demand without writing them to the local store.
• Curl installer now prompts to install the agent-skill bundle when run in an interactive terminal; set NEO4J_CLI_AUTO_INSTALL_SKILL=1 or =0 for unattended installs.
• Gate destructive operations on a new --yes --force confirmation: every */delete and */remove leaf (aura instance/deployment/agent/customer-managed-key/data-api/graphanalytics/auth-provider/cors-policy allowed-origin, docker, desktop dbms/connection, credential aura-client/dbms/embed) now requires both flags in non-TTY contexts or prompts y/N on a TTY. Back-compat break: docker delete --force (without --yes) and desktop {dbms,connection} delete --yes (without --force) now exit 2 in non-TTY contexts; pass both flags going forward.

Patch

• Add skill install support for Antigravity CLI.
• :schema now detects and reports the active graph engine (e.g. Virtual Graph) and supported Cypher versions via dbms.components(), and the query skill teaches agents which Cypher constructs to avoid on Virtual Graphs (CLI-177).
• Render temporal column values (Date, DateTime, Duration, ...) as ISO-8601 strings in query JSON and table output instead of empty {}.

v1.5.0 - 2026-05-20

Minor

• Populate next-action suggestions on Aura API errors (400/401/403/404/429) and workspace/ownership errors.
• Add Aura Agent: aura agent commands (list, get, create, update, replace, delete, invoke).
• Add --debug flag (and NEO4J_DEBUG=1 env var) on query commands to route Neo4j driver diagnostics to stderr, keeping --format json/toon stdout unaffected. Per-frame Bolt wire tracing (BoltLogger) is a deliberate follow-up pending credential redaction.
• Cap Neo4j driver ConnectionAcquisitionTimeout and MaxTransactionRetryTime at 10s on query commands so interactive failures (e.g. wrong URI scheme/port) surface within seconds instead of the driver's 1m / 30s defaults that read as a hang.
• docker create: --no-print-password suppresses generated password from stdout output (CLI-161)

Patch

• Surface an actionable suggestion when an Aura instance-type quota is exceeded (e.g. attempting to create a free-db when one already exists), and surface any panic diagnostic in the CLI's panic-recovery line so unhandled API status codes are diagnosable.
• Aura API error messages now render in the same multi-line bracket format used for auth errors instead of Go's default []string stringification.
• docker create: validate --version against allowlist (CLI-160)
• docker: redact NEO4J_AUTH/PASSWORD values in error messages from docker stderr (CLI-162)
• docs: add SECURITY.md documenting update trust root (CLI-158)
• update: warn on stderr and suggest switching to a self-managed install when --force overrides package-manager detection (CLI-157)

v1.4.0 - 2026-05-18

Minor

• Add 'docker' command tree for managing local Neo4j containers (CLI-123)
• Add organization list/get, project list/get, and workspace list/use commands; replace config project subsystem with aura.default-workspace key; deprecate aura tenant list/get (use project list and organization get instead — removal planned for a future release)
• docker create: auto-increment host ports when defaults are taken (CLI-131)
• Aura workspace is now applied to all instance, customer-managed-key, and graph-analytics session commands; --organization-id and --project-id flags resolve the target project and --tenant-id is deprecated in favour of --project-id
• Add feature-flag registry; rename aura.beta-enabled to flag.aura-beta (legacy key still read until CLI-134)
• Emit structured error envelope to stdout when --format=json or --format=toon and a command fails (CLI-140)

Patch

• Add 'upgrade' alias for the update command and 'did you mean' suggestions for typo'd subcommands
• Remove residual aura-cli source/build artifacts (standalone entrypoint, skill bundle subsystem, dead workflow gating, stale docs).
• Trim whitespace from positional ID args in remaining aura subcommands (CLI-139)
• Unknown subcommands now exit 2 (usage_error) at every nesting level instead of falling through to a help dump with the wrong exit code.

v1.3.0 - 2026-05-15

Minor

• Setting NEO4J_CLI_AUTO_INSTALL_SKILL=1 before installing via npm, Homebrew, or the curl installer now automatically runs skill install --rw after binary placement; the feature is strictly opt-in and any failure is suppressed so the install always succeeds.
• The neo4j-cli skill is now automatically refreshed in the background when the binary version changes, so agents always get up-to-date tool documentation without manual reinstall. Auto-refresh can be disabled via neo4j-cli config set skill-auto-refresh false.

v1.2.0 - 2026-05-13

Minor

• Differentiate exit codes by error category: usage (2), not-found (3), auth (4), conflict (5), validation (6), rate-limit (7), upstream (8). See neo4j-cli agent-context for the closed set. (CLI-84)
• credential dbms add: --file accepts an Aura-exported credentials file (CLI-75)
• credential aura-client add: --file accepts an Aura-exported credentials file (CLI-100)
• Auto-detect agent harnesses; --rw no longer required when running interactively in a terminal (CLI-76)
• Add usage examples to every command's --help output (CLI-93).
• Renamed --file to --env on 'credential dbms add' and 'credential aura-client add' for consistency with 'query --env' (CLI-101).
• Renamed --await to --wait on all async commands. --await is accepted as a deprecated alias for one release; see CLI-111 for removal (CLI-87).
• Remove '-f' shorthand from '--format'; '-f' is now the shorthand for 'neo4j-cli update --force' (CLI-85).
• skill bundle: surface query :schema as the schema-first workflow on SKILL.md, query --help, and :schema --help (CLI-116)

Patch

• Fix broken Aura docs URL and update subcommand wording in the 'default credential not set' error (CLI-80).
• Fix neo4j-cli exiting 0 on command errors (CLI-64).
• fix(cli): scope query/EXPLAIN --rw note to query --help only (CLI-104)

v1.1.0 - 2026-05-12

Minor

• Add neo4j-cli agent-context command emitting the full CLI shape as JSON for AI-agent discovery (CLI-83)

Patch

• Expand the query subcommand's agent skill with schema-first workflow, parameter usage, embeddings, and Cypher 25 vs Cypher 5 syntax guidance via a new query-additions.md companion document.
• Add telemetry opt-out via 'config set telemetry false' and the DO_NOT_TRACK=1 environment variable
• Suppress full --help output when a command is rejected for missing --rw, invalid --format, or unknown --credential; show only the focused error message.
• skill install/remove --help now lists every supported agent (CLI-74)
• fix(cli): keep stdout clean for --format json consumers — route narration to stderr (CLI-82, CLI-95, CLI-96), TTY-gate :schema H2 headers (CLI-94)

v1.0.0 - 2026-05-11

Major

• GA release of neo4j-cli

v0.1.0-alpha.13 - 2026-05-11

Patch

• Fix analytics HTTP timeout not being enforced when Mixpanel is unavailable — the RoundTrip adapter was calling http.Client.Post which discards the incoming request context, causing the inner client's 10-second timeout to apply instead of the configured 2-second one
• install script now defaults to ~/.local/bin on macOS to avoid requiring sudo
• Fix HuggingFace serverless embed URL to append /pipeline/feature-extraction, so sentence-transformers/* models route to feature-extraction instead of sentence-similarity (CLI-69)

v0.1.0-alpha.12 - 2026-05-11

Patch

• Fix 'update check' to print a friendly message instead of an error+usage dump, and auto-elevate via sudo when updating from a non-writable install location like /usr/local/bin.

v0.1.0-alpha.11 - 2026-05-10

Patch

• Fix install script checksum verification on macOS Tahoe (Darwin 25) by switching to POSIX-compatible sha256 flags that work with both GNU coreutils and BSD/Darwin sha256sum/shasum.
• Replace 'neo4j-cli update --check' flag with 'neo4j-cli update check' subcommand for consistency with 'skill check'.

v0.1.0-alpha.10 - 2026-05-10

Minor

• Add 'neo4j-cli update' to self-update the binary; --pre-releases opts into alpha/beta/rc, --check reports availability without installing.

v0.1.0-alpha.9 - 2026-05-08

Minor

• Add embedding support to neo4j-cli query: new :embed modifier on --param computes a vector inline (e.g. --param q:embed=hello) and feeds it as a Cypher parameter; new query :embed [text] standalone leaf prints a vector without opening a Bolt connection; five new persistent flags on query (--embed-credential, --embed-provider, --embed-model, --embed-base-url, --embed-dimensions) configure the provider (openai, ollama, huggingface). New credential embed {add,list,remove,use} subtree stores embed-provider credentials. New --embed-credential flag on credential dbms add and new credential dbms set-embed leaf link a dbms credential to a stored embed credential so query can auto-resolve embedding config from the active dbms credential.
• instance create: --name flag is now optional; when omitted, the CLI automatically generates the next available InstanceNN name within the tenant
• Fix: neo4j-cli aura instance create --type free-db now correctly stores the database name inside the dbms credential

Patch

• .env discovery for query now stops at the first .git ancestor or your $HOME boundary instead of walking the whole filesystem; when a .env above cwd is loaded, an info: loading .env from <path> line is printed to stderr so the overlay is never silent.

v0.1.0-alpha.8 - 2026-05-07

Minor

• Add --credential/-c flag to Aura resource commands (instance, tenant, deployment, dataapi, graphanalytics, customermanagedkey, import) to override the active credential per-invocation; add -c shorthand to neo4j-cli query --credential
• neo4j aura instance create now automatically saves the new instance credentials to local storage; use --credential-name to set a custom name, --no-credential-storage to skip saving, or --no-credential-print to suppress the password from output.

Patch

• Fix install-neo4j-cli.ps1 parse error on Windows PowerShell 5.1 by replacing UTF-8 glyph and box-drawing characters with ASCII equivalents; the BOM-less file was previously misread under the system ANSI codepage.

v0.1.0-alpha.7 - 2026-05-07

Patch

• Nudge agents toward --format toon in help text and skill bundles.

v0.1.0-alpha.6 - 2026-05-06

Minor

• Add 'credential dbms' commands (add, list, use, remove) and integrate stored dbms credentials into 'query' connection resolution via the '--credential' flag
• Stop building and releasing the standalone aura-cli binary; the neo4j-cli aura subcommand is the replacement
• Require --rw flag for any write operation; query run now uses the Neo4j Bolt driver (--insecure is removed; use neo4j+ssc:// for self-signed certs)

v0.1.0-alpha.5 - 2026-05-06

Minor

• Add 'skill print' command to preview the embedded SKILL.md before installing

Patch

• Emits startup event to help track usage

v0.1.0-alpha.4 - 2026-05-05

Patch

• Fix: --format or -f was not working

v0.1.0-alpha.3 - 2026-05-05

Minor

• analytics: emit command-specific events for aura (AURA), query (QUERY), and skill (SKILL) commands; query events record only the command name to prevent capturing query content or credentials that may contain PII, and include an is_aura flag derived from the --uri value
• Add toon output format option (--format toon / -f toon)

Patch

• analytics: simplify Service interface — removed EmitStartupEvent, EmitCommandEvent, EmitHelpEvent, Enable, and IsEnabled; EmitEvent now accepts an event suffix and always injects base properties at send time

v0.1.0-alpha.2 - 2026-05-05

Minor

• Add top-level neo4j config commands (config get, config set, config list) supporting dot-notation keys (e.g. neo4j config get aura.base-url, neo4j config get output)
• --output flag now applies uniformly to config and credential commands; aura credential list now renders as a table by default with name, type, and identifier columns (sensitive fields omitted)
• neo4j aura config has been removed; use neo4j config aura instead
• Add skill subcommand to install agent skills into supported AI agents (Claude Code, Cursor, Windsurf, etc.)
• neo4j-cli is now installable via npm i -g @neo4j-labs/cli
• Add 'query' command to run Cypher against a Neo4j database via the HTTP Query API
• query/:schema: auto-detect piped/redirected stdout and default --output to json
• query/:schema: send a User-Agent header (neo4j-cli/v) so server logs identify the CLI
• Renamed --output to --format and added -f as a shorthand
• distribute via Homebrew: install with brew install neo4j-labs/tap/neo4j-cli (formula auto-generated by GoReleaser on stable releases)

Patch

• Remove leftover debug log lines (help displayed, invalid command with args, command executed successfully) that were printed to stdout from the CLI entrypoint

v0.1.0-alpha.1 - 2026-05-01

Minor

• Surface credential commands at neo4j-cli top level

v0.0.1-alpha.0 - 2026-05-01

Patch

• Removed the option to enable beta aura commands
• Bugfix: aura config list now only prints valid config values