Command-Line Interface¶

Grafeo ships a single Rust CLI binary (grafeo) for querying, inspecting and maintaining databases. It includes an interactive REPL, admin commands and multiple output formats.

Installation¶

Install via any of these methods: they all provide the same CLI:

Cargo (Recommended)pip / uvnpmDownload

cargo install grafeo-cli

uv add grafeo-cli
# or
pip install grafeo-cli

npm install -g @grafeo-db/cli
# or one-shot:
npx @grafeo-db/cli --version

Pre-built binaries for all platforms are attached to every GitHub release.

Verify the installation:

grafeo version

Quick Start¶

# Create a new database
grafeo init ./mydb

# Run a query
grafeo query ./mydb "INSERT (:Person {name: 'Alix', age: 30})"
grafeo query ./mydb "MATCH (n:Person) RETURN n.name, n.age"

# Launch the interactive shell
grafeo shell ./mydb

Commands¶

Query Execution¶

# Inline query
grafeo query ./mydb "MATCH (n) RETURN n LIMIT 10"

# From a file
grafeo query ./mydb --file query.gql

# From stdin
echo "MATCH (n) RETURN count(n)" | grafeo query ./mydb --stdin

# With parameters
grafeo query ./mydb "MATCH (n {name: \$name}) RETURN n" -p name=Alix

# Choose query language (default: gql)
grafeo query ./mydb "MATCH (n) RETURN n" --lang cypher
grafeo query ./mydb "SELECT * FROM GRAPH_TABLE ..." --lang sql

# Show execution time
grafeo query ./mydb "MATCH (n) RETURN n" --timing

# Truncate wide columns
grafeo query ./mydb "MATCH (n) RETURN n" --max-width 40

Interactive Shell (REPL)¶

grafeo shell ./mydb

Grafeo 0.6.1 - Lpg mode, 42 nodes, 87 edges
Type :help for commands, :quit to exit.

grafeo> MATCH (n:Person) RETURN n.name, n.age
+----------+-------+
| n.name   | n.age |
+----------+-------+
| "Alix"   | 30    |
| "Gus"    | 25    |
+----------+-------+
2 rows (0.8ms)

grafeo> :begin
Transaction started.
grafeo[tx]> INSERT (:Person {name: 'Harm', age: 45})
grafeo[tx]> :commit
Transaction committed.

Meta-commands:

Command	Description
`:help`	Show available commands
`:quit` / Ctrl-D	Exit the shell
`:schema`	Show labels, edge types, property keys
`:info`	Show database info
`:stats`	Show detailed statistics
`:format <f>`	Set output format (`table`, `json`, `csv`)
`:timing`	Toggle query timing display
`:begin`	Start a transaction
`:commit`	Commit the current transaction
`:rollback`	Roll back the current transaction

Transaction keywords (BEGIN, COMMIT, ROLLBACK) also work as plain text.

Database Creation¶

# Create an LPG database (default)
grafeo init ./mydb

# Create an RDF database
grafeo init ./mydb --mode rdf

Inspection¶

# Overview: counts, size, mode
grafeo info ./mydb

# Detailed statistics
grafeo stats ./mydb

# Schema: labels, edge types, property keys
grafeo schema ./mydb

# Integrity check (exit code 2 on failure)
grafeo validate ./mydb

Index Management¶

grafeo index list ./mydb
grafeo index stats ./mydb

Backup & Restore¶

# Snapshot backup (single file)
grafeo backup create ./mydb -o backup.grafeo
grafeo backup restore backup.grafeo ./restored --force

# Full and incremental backups (WAL-based, for production use), in one directory
grafeo backup full ./mydb -o /backups
grafeo backup incremental ./mydb -o /backups
grafeo backup status /backups
grafeo backup restore-to-epoch /backups --epoch 100 -o ./restored

Data Import¶

# Import CSV as graph nodes
grafeo import csv data.csv --path ./mydb --label Person
grafeo import csv data.csv --path ./mydb --label Person --headers false --separator ';'

# Import JSON Lines as graph nodes
grafeo import jsonl events.jsonl --path ./mydb --label Event

Data Export¶

# Native dump and load (JSON Lines, the default graph)
grafeo data dump ./mydb -o graph.jsonl
grafeo data load graph.jsonl ./newdb

# Graph interchange formats
grafeo data dump ./mydb -o graph.gexf --export-format gexf
grafeo data dump ./mydb -o graph.graphml --export-format graphml

data load adds the graph of a JSON Lines file to a database, in one transaction: if a line fails, the error names it and the database is left as it was. Each line is a node or an edge. Edges name their nodes by the node's id in the file (nodes may come in any order, and each gets a new ID), and property values are plain JSON or tagged with their type, as data dump writes them:

{"type":"node","id":3,"labels":["Person"],"properties":{"name":"Alix","born":{"Date":6652}}}
{"type":"node","id":19,"labels":["Person"],"properties":{"name":"Gus"}}
{"type":"edge","source":3,"target":19,"edge_type":"KNOWS","properties":{"since":2019}}

A plain integer that fits 64 bits loads as an INT64, a larger one up to 38 digits as an exact DECIMAL (past that the load fails, naming the line), and a number with a fraction or an exponent as a FLOAT64. A dump writes a DECIMAL with its text and scale, {"Decimal":"1.50"}, which a load reads back.

WAL Management¶

grafeo wal status ./mydb
grafeo wal checkpoint ./mydb

Compaction¶

grafeo compact ./mydb
grafeo compact ./mydb --dry-run

Shell Completions¶

# Generate completions for your shell
grafeo completions bash > ~/.local/share/bash-completion/completions/grafeo
grafeo completions zsh > ~/.zfunc/_grafeo
grafeo completions fish > ~/.config/fish/completions/grafeo.fish
grafeo completions powershell >> $PROFILE

Version & Build Info¶

$ grafeo version
grafeo 0.6.1

Build:
  rustc:    1.99.0
  target:   x86_64
  os:       linux
  features: gql, cypher, sparql, sql-pgq

Paths:
  config:   /home/user/.config/grafeo
  history:  /home/user/.config/grafeo/history

Output Formats¶

All commands support multiple output formats:

# Auto-detect: table on TTY, JSON when piped
grafeo info ./mydb

# Explicit format
grafeo info ./mydb --format table
grafeo info ./mydb --format json
grafeo info ./mydb --format csv

Standard output holds only results, in the chosen format: progress and status lines (Creating full backup of ..., the row count of a query) go to standard error, and --quiet leaves them out. So --format json prints JSON for every command; a command that acts, such as backup full, import csv or data dump, prints a record of what it did ({"kind": "full", "file": "backup_full_0000.grafeo", "start_epoch": 0, "end_epoch": 2, "size_bytes": 45056}).

In JSON a query result is an array with an object per row, its keys in the order of the columns. Values keep their JSON type: numbers (a decimal that a number would round stays text), true and false, null, strings, arrays for lists and vectors, objects for maps; dates, times and durations are their text ("1988-03-19"). In CSV and tables a value is its text, a string without quotes; inside a list or a map strings are quoted, as in ["canals", "bridges"].

Global Options¶

Option	Description
`--format <auto\\|table\\|json\\|csv>`	Output format (default: `auto`)
`--quiet`, `-q`	Suppress progress and status messages; results still print
`--verbose`, `-v`	Enable debug logging
`--no-color`	Disable colored output (also respects `NO_COLOR` env var)
`--color`	Force colored output even when piped
`--help`	Show help
`--version`	Show version

Exit Codes¶

Code	Meaning
0	Success
1	General error (runtime, I/O, query)
2	Validation failed (`grafeo validate` found errors)

Python API Equivalents¶

The Python API provides the same functionality programmatically:

import grafeo

db = grafeo.GrafeoDB("./mydb")

# Equivalent to: grafeo info ./mydb
print(db.info())

# Equivalent to: grafeo stats ./mydb
print(db.detailed_stats())

# Equivalent to: grafeo schema ./mydb
print(db.schema())

# Equivalent to: grafeo validate ./mydb
print(db.validate())

# Equivalent to: grafeo query ./mydb "MATCH (n) RETURN n"
result = db.execute("MATCH (n) RETURN n")

Migrating from the Python CLI¶

Python CLI removed in 0.4.4

The grafeo[cli] Python CLI (Click-based) has been removed. Install the Rust binary instead via cargo install grafeo-cli, pip install grafeo-cli, or npm install -g @grafeo-db/cli. All previous commands are available with the same syntax, plus new features: query, shell, init, CSV output and shell completions.