neo4j-cli 0.1.0a8

Neo4j CLI

Neo4j CLI

Installation

Prebuilt archives (recommended)

Download the archive for your OS/arch from the releases page and extract the neo4j-cli binary.

npm

npm i -g @neo4j-labs/cli

Installs a small Node wrapper plus a prebuilt neo4j-cli binary matching your OS and CPU. pnpm add -g @neo4j-labs/cli and yarn global add @neo4j-labs/cli work the same way. Prereleases via npm i -g @neo4j-labs/cli@alpha (also @beta, @rc, @next). See distribution/npm/cli/README.md for the supported platform matrix.

Note: To install a pre-release, the version must be specified for pip, pipx etc.. This is achieved by adding == immediately after neo4j-cli with the version you want. For example, pipx install neo4j-cli==0.1.0a6 will install 0.1.0a6 of Neo4j CLI

pip

pip install neo4j-cli

pipx

pipx install neo4j-cli

uv

uv tool install neo4j-cli

uvx

uvx will install and execute neo4j-cli. This means that you must include the commands you want to use with uvx

uvx -i neo4j-cli YOUR_COMMANDS

Check the installation by running neo4j-cli --help

Usage

Extract the executable to a directory of your choosing.

Create Aura API Credentials in your Account Settings, and note down the client ID and secret.

Add these credentials into the CLI with a name of your choosing:

./neo4j-cli aura credential add --name "Aura API Credentials" --client-id <client-id> --client-secret <client-secret>

This will add and set the credential as the default credential for use.

You can then, for example, list your instances in a table format:

./neo4j-cli aura instance list --format table

If you would rather just type neo4j-cli then move the neo4j-cli binary into the file path of your computer.
Windows:

move neo4j-cli.exe c:\windows\system32

Mac:

sudo mv neo4j-cli /usr/local/bin

To see all of the available commands:

./neo4j-cli

Help for each command is accessed by using it without any flags or options. For example, to see help creating an instance:

./neo4j-cli aura instance create

Querying Neo4j

neo4j-cli query runs Cypher against any Neo4j database via the Bolt protocol. Cypher comes from the positional argument or piped stdin.

./neo4j-cli query 'RETURN 1 AS n'
echo 'MATCH (n) RETURN count(n)' | ./neo4j-cli query

Connection settings are resolved with this precedence (highest first): flag → env var → .env file (auto-discovered by walking up from cwd) → built-in default.

Setting	Flag	Env var	Default
URI	--uri	NEO4J_URI	neo4j://localhost:7687
Username	--username	NEO4J_USERNAME	neo4j
Password	--password	NEO4J_PASSWORD	prompted on TTY
Database	--database	NEO4J_DATABASE	neo4j

http:// and https:// URIs are auto-rewritten to neo4j://<host>:7687 and neo4j+s://<host>:7687 respectively (path/query stripped). For self-signed certs use neo4j+ssc://.

Pass parameters with --param key=value (repeatable). Values that parse as JSON are typed; everything else is a string:

./neo4j-cli query 'MATCH (p:Person {name:$name}) RETURN p' --param name=Alice
./neo4j-cli query 'RETURN $ids' --param 'ids=[1,2,3]'
echo 'MATCH (p:Person {name:$name}) RETURN p' | ./neo4j-cli query --param name=Alice

Output is a table by default; pass --format json for a stable envelope (columns, rows, truncated, arrays_truncated). When stdout is not a terminal (piped or redirected), --format defaults to json. Applies to both query and :schema. Large results are capped at 100 rows and arrays inside cells at 100 items — tune with --max-rows / --truncate-arrays-over (0 = unlimited).

Schema introspection:

./neo4j-cli query :schema

Write operations

Write commands require --rw. neo4j-cli query runs EXPLAIN first when --rw is absent and blocks mutating Cypher before execution.

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

Agent skills

neo4j-cli ships an embedded skill bundle (SKILL.md + per-subcommand references) that teaches AI coding agents how to drive the CLI. skill install drops that bundle into the supported agents' skill directories so the agent picks it up on next run.

Supported agents:

• Claude Code
• Cursor
• Windsurf
• Copilot
• Gemini CLI
• Cline
• Codex
• Pi
• OpenCode
• Junie

Install into every detected agent (or pass an agent name to target one):

./neo4j-cli skill install
./neo4j-cli skill install claude-code

List supported agents and per-agent install state:

./neo4j-cli skill list

Check installed bundles for version drift against the running binary:

./neo4j-cli skill check

Remove the installed bundle (idempotent):

./neo4j-cli skill remove
./neo4j-cli skill remove claude-code

Beta features (commands gated by AuraBetaEnabled, e.g. dataapi, import, deployment) are not included in the generated bundle — the bundle reflects the default-config command surface.

Feedback / Issues

Please use GitHub issues to provide feedback and report any issues that you have encountered.

Building locally

Clone the repository and run:

make build

This produces bin/neo4j-cli. To run without building:

make run-neo4j

Developing and contributing

Read CONTRIBUTING.md