CLI

kglite-cli ships the standalone kglite command for working with .kgl graph files without starting a server. It has two modes:

  • one-shot commands for scripts and agents

  • an interactive Cypher shell for humans

Install it from PyPI or crates.io:

pip install kglite-cli
# or
cargo install kglite-cli

kglite-cli is separate from the Python kglite package. Installing it puts the kglite binary on PATH.

One-Shot Commands

Run a read-only Cypher query and exit:

kglite query app.kgl "MATCH (n:Person) RETURN n.name AS name" --format json

Run a write statement and save the graph:

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

--write-scope restricts writes to the listed node and relationship types. --git-sha and --modified-by stamp provenance on auto_timestamp types.

Inspect a dependency frontier:

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

Print the agent-oriented graph description:

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

describe returns the same XML schema document exposed by the Python API and MCP server, including focused views for labels, Cypher support, and connection types.

Agent Sessions

Use session when an agent needs multiple operations against the same graph. The process keeps one graph loaded in memory and accepts JSONL requests on stdin:

kglite session app.kgl --format json

Example request stream:

{"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"}

Responses echo id when provided. In JSON mode, query and write return typed rows; table and CSV modes return rendered output.

For focused descriptions, agents can use compact or explicit object forms:

{"op":"describe","connections":true}
{"op":"describe","connections":["KNOWS"]}
{"op":"describe","connections":{"detail":"overview"}}
{"op":"describe","connections":{"types":["KNOWS"]}}

The same object style works for types, cypher, and fluent detail selectors where applicable.

Interactive Shell

Open the shell with a graph path:

kglite app.kgl

Run with no path for a scratch in-memory graph:

kglite

Cypher statements execute when terminated by ;, so a query can span multiple lines. Dot-commands execute on Enter. Tab completion covers dot-commands and graph labels.

Common dot-commands:

  • .help — list commands

  • .quit / .exit — leave the shell

  • .labels / .rels / .schema / .indexes — inspect schema

  • .mode table|csv|json — set output format

  • .import <file.csv> <NodeType> [--id <col>] [--title <col>] — import CSV rows as nodes

  • .dump <dir> — export CSV files plus a blueprint.json

  • .read <file> — run Cypher statements from a file

  • .save [path] — save the graph to a .kgl file

  • .timing on|off — show query wall time

Ctrl-C cancels a running query. Ctrl-D exits.

Other Commands

export-text prints the deterministic text projection used by git textconv:

kglite export-text app.kgl

diff compares two graph projections:

kglite diff before.kgl after.kgl