Tooling · Reference

CLI Reference.

The kgl command provides five subcommands: parse, lint, query, graph, and schema. Installed via pip alongside a companion language server for VS Code.

Installation

bash

pip install kgl-lang

# Verify
kgl --version

Commands

`kgl parse <file>`

Parse a single .kgl file and print each node as a structured summary.

bash

kgl parse people/alice.kgl

output

Parsed 1 node(s) from people/alice.kgl
  - Alice Nguyen [Person]
    joined: 2021-03-15
    role: engineer
    Links: 3

Flags:

Flag	Default	Description
`--format text\|json`	`text`	Output format. JSON includes node fields, tags, body, and link count.

`kgl lint [directory]`

Walk all .kgl files under directory (default: current directory), load schema, and report linter warnings grouped by file.

bash

kgl lint ./

output

Found 2 warning(s):

  W001: @Person "Charlie Watts" — missing required field 'joined'
  W002: @Person "Charlie Watts" — node type not defined in schema

Exit codes:

Code	Meaning
`0`	No warnings
`1`	Warnings found

Flags:

Flag	Default	Description
`--format text\|json`	`text`	Output format
`-v`, `--verbose`	off	Include file paths in output

`kgl query <directory> "<cypher>"`

Load the graph from directory, run an OpenCypher query, and print results. See OpenCypher for supported query syntax.

bash

kgl query ./ "MATCH (p:Person)-[r:mentors]->(q:Person) RETURN p.name, q.name, r.started"

output — aligned table

Query results: 1 row(s)

  p.name        q.name      r.started
  ────────────  ──────────  ──────────
  Alice Nguyen  Diana Park  2023-06

Flags:

Flag	Default	Description
`--format text\|json\|csv`	`text`	JSON: array of objects. CSV: includes header row.

json output

kgl query ./ "MATCH (n:Person) RETURN n.name" --format json

csv output

kgl query ./ "MATCH (n:Person) RETURN n.name" --format csv

`kgl graph [directory]`

Print a text summary of the loaded graph: node count by type, edge count by relationship type, and unresolved links.

bash

kgl graph ./

output

Graph: ./
  Nodes: 8
  Edges: 12
  Unresolved: 0

Node types: Person, Project, Service
Edge types: depends-on, mentors, works-on

Flags:

Flag	Default	Description
`--format text\|json`	`text`	Output format
`-v`, `--verbose`	off	Show unresolved link paths

`kgl schema [directory]`

Show all node type and relationship type definitions loaded from _schema.kgl files.

bash

kgl schema ./

output

Schema loaded from: ./

Node types (3):
  Contractor extends Person
    contract-end: date (required)
  Person
    joined: date (required)
    role: text (optional)
  Project
    status: text (required)
    deadline: date (optional)

Flags:

Flag	Default	Description
`--format text\|json`	`text`	Output format

Language server

A companion kgl-lsp command is also installed. It is a Language Server Protocol server for VS Code (see VS Code Extension). It is not intended to be called directly — VS Code spawns it automatically when the first .kgl file is opened.