Skip to content

Velr CLI

velr is the command-line shell for Velr. It can run one query and exit, read queries from stdin, or open an interactive REPL for exploring a Velr database.

Install

On macOS, the recommended install path is the Velr Homebrew tap. The same tap also works on Linux and Windows Subsystem for Linux (WSL) for users who manage CLI tools with Homebrew:

brew tap velr-ai/velr
brew install velr

If Homebrew is configured to require trust for third-party taps and refuses to load the formula, trust the Velr formula once and rerun the install:

brew trust --formula velr-ai/velr/velr
brew install velr

The Homebrew formula installs the prebuilt Velr CLI archive for your platform. It does not require a local Rust toolchain.

For Linux users who prefer direct binaries, Windows users, and manual installs, prebuilt archives are published on the velr-ai/velr releases page for macOS, Linux, and Windows. Download the archive for your platform, unpack it, and place velr or velr.exe somewhere on your PATH.

The macOS release archive binaries are unsigned. We recommend Homebrew on macOS. If you still want to use the release archive, remove the quarantine attribute after unpacking:

xattr -d com.apple.quarantine /path/to/velr

Verify the install:

velr --version
velr --help

velr --version prints both the CLI release and the linked Rust driver version, for example velr-cli 0.2.36 (velr driver 0.2.32).

Quickstart

Run a query against an in-memory database:

velr -e 'RETURN 1 AS n'

Use a database file:

velr graph.db -e 'CREATE (:Person {name: "Ada"});'
velr graph.db -e 'MATCH (p:Person) RETURN p.name AS name;'

Pipe a script into the CLI:

printf 'RETURN 1 AS n; RETURN 2 AS m;\n' | velr

Explain a query without executing it:

velr --explain 'MATCH (p:Person) RETURN p.name AS name'

Start the interactive shell:

velr graph.db

Execution Modes

velr chooses a mode from the arguments and stdin:

  • velr -e '<query>' executes query text and exits.
  • velr <db-path> -e '<query>' executes against a file-backed database.
  • echo '<query>' | velr reads query text from stdin.
  • velr starts an in-memory REPL when stdin is a terminal.
  • velr <db-path> starts a REPL against that database file.
  • velr --explain '<query>' prints a compact explain trace without executing the query.
  • echo '<script>' | velr --explain explains every statement in the script.

Database paths that start with - are rejected so a misspelled flag cannot silently create a database file. On Windows, /flag style arguments are also rejected for the same reason.

Interactive Shell

In the REPL, query input is submitted when the buffer ends with ;. Pressing Enter before the final semicolon continues the query on the next line.

~/project〉MATCH (p:Person)
:: WHERE p.name = "Ada"
:: RETURN p;

REPL commands:

  • :source <file> executes queries from a file.
  • :pwd prints the current working directory.
  • :cd [dir] changes directory; without an argument it goes to your home directory.
  • :ls [path] lists files in the current directory or a provided path.
  • :help or :h shows REPL help.
  • :quit, :exit, :q, Ctrl+C, or Ctrl+D exits.

Example session:

~/project〉:pwd
/Users/sam/project

~/project〉:ls
demo.cypher
data/

~/project〉:source demo.cypher

Output

Use --format or -f to choose the output format:

  • styled uses a terminal-friendly table and is the default on a TTY.
  • plain uses a simple ASCII table.
  • tsv is tab-separated and is the default when stdout is not a TTY.
  • csv is comma-separated.
  • ndjson emits one JSON object per row.

Examples:

velr -f plain -e 'MATCH (n) RETURN n'
velr -f csv -e 'MATCH (p:Person) RETURN p.name AS name'
velr -f ndjson -e 'MATCH (p:Person) RETURN p'

--stats prints timing information to stderr, so stdout remains usable by scripts:

velr -f ndjson --stats -e 'MATCH (p:Person) RETURN p.name AS name'

Explain

There are two explain workflows:

  • --explain '<query>' asks the public Rust driver for a compact explain trace and does not execute the query.
  • -e 'EXPLAIN ...' or -e 'EXPLAIN ANALYZE ...' executes the statement through the driver and renders the result tables in the selected format.
velr --explain 'RETURN 1 AS n'
velr -f plain -e 'EXPLAIN RETURN 1 AS n'
velr -f ndjson -e 'EXPLAIN ANALYZE RETURN 1 AS n'

Scripts

A script may contain multiple semicolon-terminated statements:

CREATE (:Person {name: "Ada"});
MATCH (p:Person) RETURN p.name AS name;

Run it from the shell:

velr graph.db < demo.cypher

Or from inside the REPL:

~/project〉:source demo.cypher

Exit Codes

  • 0: success
  • 1: query or runtime error
  • 2: usage error

License

The CLI source is licensed under MIT. Prebuilt binary archives also include the Velr runtime binary redistribution license.