velesdb-cli

The velesdb command line: an interactive VelesQL REPL and offline admin CLI for a VelesDB database.

Objective

A VelesDB database is a directory on disk. Without a client you cannot see what is inside it, try a query, or fix a collection — you have to write a Rust program or start a server first. velesdb-cli removes that step: it opens the database directory directly and gives you a REPL and a set of subcommands to create collections, ingest vectors, run VelesQL (vector + graph + metadata), read execution plans and export data. No server, no daemon, no network.

It is the command line of VelesDB, the explainable local-first memory engine for AI agents; the why() recall trail that explains an answer lives in velesdb-memory.

Use cases

• Inspecting a database someone else produced: which collections, which dimensions, how many points, what the payloads actually look like.
• Trying a VelesQL query interactively and reading its plan before wiring it into an application or an SDK call.
• Bulk-loading an embedding dump (JSONL, CSV or VRB1 binary) into a fresh collection from a shell script or a CI job.
• Auditing and repairing a graph collection built by an older version (velesdb graph doctor).
• Exporting a collection to JSON to diff it, archive it or move it elsewhere.

Prerequisites

No running velesdb-server is required — every subcommand works offline against the database directory.

Installation

cargo install velesdb-cli

The binary is named velesdb (not velesdb-cli).

From source, inside a clone of the repository:

cargo install --path crates/velesdb-cli

Prebuilt binaries (Linux x86_64, macOS x86_64 and aarch64, Windows x86_64) and the Docker image are covered in docs/guides/INSTALL_OPTIONS.md and docs/guides/INSTALLATION.md; building the Debian package yourself is documented in the CLI reference.

First success in 60 seconds

Copy the whole block into a shell. It creates a database in the current directory, inserts two points and runs a vector search.

velesdb collection create ./data quickstart --dimension 4 --metric cosine

velesdb data upsert ./data quickstart --id 1 \
  --vector '[1.0, 0.0, 0.0, 0.0]' \
  --payload '{"title":"Rust in action","category":"tech"}'

velesdb data upsert ./data quickstart --id 2 \
  --vector '[0.0, 1.0, 0.0, 0.0]' \
  --payload '{"title":"Graph theory","category":"math"}'

velesdb query execute ./data \
  "SELECT * FROM quickstart WHERE vector NEAR [1.0, 0.0, 0.0, 0.0] LIMIT 2"

Expected output — the three ✅ lines then the result table:

✅ Vector collection 'quickstart' created (4 dims, Cosine, Full)
✅ Upserted point 1 into 'quickstart'
✅ Upserted point 2 into 'quickstart'
┌────┬──────────┬────────────────┐
│ id ┆ category ┆ title          │
╞════╪══════════╪════════════════╡
│ 1  ┆ tech     ┆ Rust in action │
├╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
│ 2  ┆ math     ┆ Graph theory   │
└────┴──────────┴────────────────┘

Anything else is a failure: a line starting with Error: means the command aborted (see Troubleshooting), and No results. instead of the table means the query ran but matched nothing.

Then open the REPL on the same database:

velesdb repl ./data

VelesDB v4.0.0 - VelesQL REPL
Database: ./data
Type .help for commands, .quit to exit

velesdb>

Type .collections, then .quit to leave.

Configuration

Cargo features: default = ["velesdb-core/default", "update-check"], plus gpu and loom, all forwarded to velesdb-core.

Examples

• First success in 60 seconds above — vector collection, upsert, search.
• VelesQL cookbook — runnable snippets for vector, hybrid, sparse, temporal, graph MATCH, aggregation, set operations and JOIN queries.
• Business scenarios — end-to-end walkthroughs.

Commands

velesdb --help and velesdb <command> --help are authoritative; the tables below are the map.

REPL dot-commands (.schema, .explain-analyze, .graph …), backslash session commands (\set, \use) and session settings are documented in the REPL reference.

This crate ships a binary only — there is no public Rust API to import. To embed VelesDB in a Rust program, use velesdb-core instead.

Known limits

• The REPL is single-line. A command or query must fit on one line; multi-line input is not supported.
• No bind parameters in the REPL ($v, $query): there is no mechanism to pass external values. Use literal vectors, or the REST API POST /query with params.
• LEFT JOIN / RIGHT JOIN and subqueries parse but do not execute — they raise a runtime error. INNER JOIN is fully supported.
• data upsert, data export, data get and data delete are vector-only — they reject graph and metadata collections.
• data import reads .jsonl, .ndjson, .csv, .bin/.vrb1 only; VRB1 carries no payloads.
• No concurrent server access. Opening a database acquires an exclusive file lock, so the CLI cannot share a directory with a running velesdb-server — see CONCURRENCY_LOCKING.md.
• .agent is a preview and not yet fully implemented in the CLI.

Compatibility

velesdb-cli is a human/script-facing CLI, not an MCP server — for agent-facing access use velesdb-memory. Platforms below get a prebuilt binary in each GitHub release; any other target can be built with cargo install velesdb-cli.

Troubleshooting

License

Licensed under the VelesDB Core License 1.0 (source-available).

velesdb-cli v4.1.0 · Last updated: 2026-07-25 · Applies to: velesdb-core 4.1.0 · Report a docs error