Metadata-Version: 2.4
Name: kglite-cli
Version: 0.17.8
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Topic :: Database
License-File: LICENSE
Summary: Pure-Rust KGLite CLI: an interactive Cypher shell for .kgl knowledge graphs.
Keywords: cypher,repl,shell,knowledge-graph,kglite
Home-Page: https://github.com/kkollsga/kglite
License-Expression: MIT
Requires-Python: >=3.8
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Homepage, https://github.com/kkollsga/kglite
Project-URL: Repository, https://github.com/kkollsga/kglite

# kglite-cli

The interactive Cypher shell for [kglite](https://github.com/kkollsga/kglite)
knowledge graphs — the `sqlite3`-style REPL for `.kgl` files.

## Install

```console
$ pip install kglite          # Python API plus the `kglite` command
# or
$ pip install kglite-cli      # standalone CLI-only binary wheel
# or
$ cargo install kglite-cli    # standalone build (needs a Rust toolchain)
```

The main `kglite` wheel embeds this crate's Rust library and exposes the same
command through a thin console-script shim. `kglite-cli` remains the standalone
libpython-free binary distribution; install one route or the other.

The code-review Agent Skill is installed by
[codingest](https://github.com/kkollsga/codingest), which also builds the code
graphs the skill queries:

```console
$ codingest skill install
```

## Use

Run one query and exit:

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

Run a scoped write and persist it:

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

Inspect a dependency frontier:

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

Ask for the agent-oriented graph description:

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

Build a code-review graph without Python or MCP configuration:

```console
# Code-graph builds live in the codingest project's CLI:
$ codingest build . --output .kglite/code-review.kgl
$ codingest status --output .kglite/code-review.kgl
```

The adjacent metadata sidecar records the source and revision fingerprint so
`status` can detect a stale working-tree artifact or a revision label that
moved.

Keep one graph loaded for an agent loop:

```console
$ 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:

```console
$ 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.

Piped input (`kglite app.kgl < script.cypher`) additionally runs a balanced
trailing statement at end of input and before a dot-command line, so a script
whose last statement has no `;` still runs; an unbalanced tail is reported on
stderr with a non-zero exit. Table cells are width-capped only on a terminal.

## 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, including `<skills>` and `<recipes>` indexes when the graph carries them
- `skill <graph.kgl> [name] [--format table|csv|json]` — list the skills the graph carries (sorted, `--format` honoured), or print one body raw on stdout. Read-only, no writer lease. Exits non-zero when the named skill is absent; a graph with no skills lists zero rows and exits 0. Skills and recipe queries are written from Python (`set_skill` / `set_recipe`), not here
- `okf check <dir> [--dialect obsidian|okf|loose] [--strict] [--json]` — check a vault directory against the `VAULT.md` format and print the build report (counts, then errors, then warnings). Exits non-zero on any error; `--strict` counts warnings too. Runs the same read the build runs, so it reports what a build does
- `okf build <dir> -o <graph.kgl> [--dialect obsidian]` — build a vault into a `.kgl`; the report goes to stderr, stdout names the file written
- `okf status <dir> [--graph <graph.kgl>] [--dialect obsidian]` — print the vault's fingerprint (a `stat` pass; no note is read). With `--graph`, compare it against the one stamped in the `.kgl` at build time: `current` exits 0, `stale` exits non-zero. Keep the `.kgl` outside the vault — a file inside it is part of what the fingerprint covers
- `okf export <graph.kgl> <dir> [--force] [--source-root <dir>]` — write a `.kgl` back out as a vault. Only files a previous export wrote are replaced or removed; anything else is refused, named on stderr and exits non-zero (`--force` lifts that). `--source-root` names the directory the graph's attachments were read from, so their bytes are copied too; omitted, the graph's own recorded source root stands in
- `session <graph.kgl>` — process JSONL requests against one in-memory graph (`query`, `write`, `describe`, `save`, `help`, `exit`); `{"op":"help"}` returns the op table
- `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.

