kglite-cli

The interactive Cypher shell for kglite knowledge graphs — the sqlite3-style REPL for .kgl files.

Install

$ pip install kglite-cli      # ships the `kglite` binary on PATH
# or
$ cargo install kglite-cli    # build from source (needs a Rust toolchain)

kglite-cli is a standalone binary distribution — installing it gives you the kglite command. It's independent of the kglite Python library; install either or both.

Use

Run one query and exit:

$ kglite query app.kgl "MATCH (n:Person) RETURN n.name AS name" --format json
[
  {
    "name": "Alice"
  }
]

Run a scoped write and persist it:

$ kglite write app.kgl "CREATE (:Task {id:'t1', status:'todo'})" \
    --save --write-scope Task --git-sha abc123 --modified-by agent

Inspect a dependency frontier:

$ kglite ready-set app.kgl --done 'n.status = "done"' --node-type Task --format csv

Ask for the agent-oriented graph description:

$ kglite describe app.kgl
$ kglite describe app.kgl --types Task
$ kglite describe app.kgl --cypher

Keep one graph loaded for an agent loop:

$ kglite session app.kgl --format json
{"op":"describe","types":["Task"]}
{"id":"w1","op":"write","query":"CREATE (:Task {id:'t1', status:'todo'})"}
{"id":"q1","op":"query","query":"MATCH (t:Task) RETURN count(t) AS n","format":"json"}
{"op":"save"}
{"op":"exit"}

Session JSON responses echo id when provided. JSON-mode query/write responses return typed rows; table/csv modes return rendered output. For describe, the compact forms still work ("connections":true, "connections":["KNOWS"]), and agents can use explicit object forms: "connections":{"detail":"overview"} or "connections":{"types":["KNOWS"]}.

Or open the interactive shell:

$ kglite app.kgl
kglite shell — app.kgl
Type .help for commands, .quit to exit.
kglite> MATCH (n:Person) RETURN n.name AS name LIMIT 3;
name
----
Alice
Bob
Carol
(3 rows)
kglite> .quit

Run with no path for a scratch in-memory graph ($ kglite). Pure-Rust single binary over kglite::api::* — no Python, no server.

A Cypher statement runs when terminated by ;, so it can span multiple lines; dot-commands run on Enter. Tab completes dot-commands and the graph's labels.

Commands

Non-interactive commands:

• query <graph.kgl> <cypher> [--format table|csv|json] — run a read-only Cypher query
• write <graph.kgl> <cypher> [--format table|csv|json] [--save] — run a write-capable Cypher statement
• write --write-scope A,B --git-sha <sha> --modified-by <actor> — restrict writes and stamp provenance on auto_timestamp types
• ready-set <graph.kgl> --done <predicate> [--relationship DEPENDS_ON] [--node-type T] — print CALL ready_set(...)
• describe <graph.kgl> [--types T] [--cypher] [--connections] — print the XML describe() document for agents
• session <graph.kgl> — process JSONL requests against one in-memory graph (query, write, describe, save, exit)
• export-text <graph.kgl> — print the deterministic text projection used by git textconv
• diff <a.kgl> <b.kgl> — compare two graph text projections

Interactive dot-commands:

• .help — list commands
• .quit / .exit — leave the shell
• .labels / .rels / .schema / .indexes — schema introspection
• .mode table|csv|json — set the output format
• .import <file.csv> <NodeType> [--id <col>] [--title <col>] — load a CSV as nodes
• .dump <dir> — export a portable CSV + blueprint.json copy (reload with kglite.from_blueprint(...))
• .read <file> — run the Cypher statements in a file
• .save [path] — write the graph to a .kgl file
• .timing on|off — show query wall-time after each statement

Anything else is executed as Cypher. Ctrl-C cancels a running query; Ctrl-D exits.